OpenEuphoria

8.28 Euphoria Database (EDS)

8.28.1 Error Status Constants

8.28.1.1 DB_OK

include std/eds.e
namespace eds
public enum DB_OK

Database is OK, not error has occurred.

8.28.1.2 DB_OPEN_FAIL

include std/eds.e
namespace eds
public enum DB_OPEN_FAIL

The database could not be opened.

8.28.1.3 DB_EXISTS_ALREADY

include std/eds.e
namespace eds
public enum DB_EXISTS_ALREADY

The database could not be created, it already exists.

8.28.1.4 DB_LOCK_FAIL

include std/eds.e
namespace eds
public enum DB_LOCK_FAIL

A lock could not be gained on the database.

8.28.1.5 DB_BAD_NAME

include std/eds.e
namespace eds
public enum DB_BAD_NAME

An invalid name suppled when creating a table.

8.28.1.6 DB_FATAL_FAIL

include std/eds.e
namespace eds
public enum DB_FATAL_FAIL

A fatal error has occurred.

8.28.2 Lock Type Constants

8.28.2.1 DB_LOCK_NO

include std/eds.e
namespace eds
public enum DB_LOCK_NO

Do not lock the file.

8.28.2.2 DB_LOCK_SHARED

include std/eds.e
namespace eds
public enum DB_LOCK_SHARED

Open the database with read-only access but allow others to update it.

8.28.2.3 DB_LOCK_EXCLUSIVE

include std/eds.e
namespace eds
public enum DB_LOCK_EXCLUSIVE

Open the database with read and write access.

8.28.2.4 DB_LOCK_READ_ONLY

include std/eds.e
namespace eds
public enum DB_LOCK_READ_ONLY

Open the database with read-only access and ignore others updating it

8.28.3 Error Code Constants

8.28.3.1 MISSING_END

include std/eds.e
namespace eds
public enum MISSING_END

Missing 0 terminator

8.28.3.2 NO_DATABASE

include std/eds.e
namespace eds
public enum NO_DATABASE

current_db is not set

8.28.3.3 BAD_SEEK

include std/eds.e
namespace eds
public enum BAD_SEEK

io:seek() failed.

8.28.3.4 NO_TABLE

include std/eds.e
namespace eds
public enum NO_TABLE

no table was found.

8.28.3.5 DUP_TABLE

include std/eds.e
namespace eds
public enum DUP_TABLE

this table already exists.

8.28.3.6 BAD_RECNO

include std/eds.e
namespace eds
public enum BAD_RECNO

unknown key_location index was supplied.

8.28.3.7 INSERT_FAILED

include std/eds.e
namespace eds
public enum INSERT_FAILED

couldn't insert a new record.

8.28.3.8 LAST_ERROR_CODE

include std/eds.e
namespace eds
public enum LAST_ERROR_CODE

last error code

8.28.3.9 BAD_FILE

include std/eds.e
namespace eds
public enum BAD_FILE

bad file

8.28.4 Indexes for connection option structure.

8.28.4.1 CONNECT_LOCK

include std/eds.e
namespace eds
public enum CONNECT_LOCK

Locking method

8.28.4.2 CONNECT_TABLES

include std/eds.e
namespace eds
public enum CONNECT_TABLES

Initial number of tables to create

8.28.4.3 CONNECT_FREE

include std/eds.e
namespace eds
public enum CONNECT_FREE

Initial number of free pointers to create

8.28.5 Database connection options

8.28.5.1 DISCONNECT

include std/eds.e
namespace eds
public constant DISCONNECT

Disconnect a connected database

8.28.5.2 LOCK_METHOD

include std/eds.e
namespace eds
public constant LOCK_METHOD

Locking method to use

8.28.5.3 INIT_TABLES

include std/eds.e
namespace eds
public constant INIT_TABLES

The initial number of tables to reserve space for when creating a database.

8.28.5.4 INIT_FREE

include std/eds.e
namespace eds
public constant INIT_FREE

The initial number of free space pointers to reserve space for when creating a database.

8.28.5.5 CONNECTION

include std/eds.e
namespace eds
public constant CONNECTION

Fetch the details about the alias

8.28.6 Variables

8.28.6.1 db_fatal_id

include std/eds.e
namespace eds
public integer db_fatal_id

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.

8.28.7 Routines

8.28.7.1 db_get_errors

include std/eds.e
namespace eds
public function db_get_errors(integer clearing = 1)

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

Parameters:

1. 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.

1. Error Code.
2. Error Text.
3. Name of library routine that recorded the error.
4. 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

8.28.7.2 db_dump

include std/eds.e
namespace eds
public procedure db_dump(object file_id, integer low_level_too = 0)

print the current database in readable form to file fn

Parameters:

1. fn : the destination file for printing the current Euphoria database;
2. 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.

8.28.7.3 check_free_list

include std/eds.e
namespace eds
public procedure check_free_list()

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.

8.28.8 Managing databases

8.28.8.1 db_connect

include std/eds.e
namespace eds
public function db_connect(sequence dbalias, sequence path = "", sequence dboptions = {})

Define a symbolic name for a database, and its default attributes.

Parameters:

1. dbalias : a sequence. This is the symbolic name that the database can be referred to by.
2. path : a sequence, the path to the file that will contain the database.
3. dboptions: a sequence. Contains the set of attributes for the database. The default is {} meaning it will use the various EDS default values.

Returns:

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

Comments:

• This does not create or open a database. It only associates a symbolic name with a database path. This name can then be used in the calls to db_create(), db_open(), and db_select() instead of the physical database name.
• If the file in the path does not have an extention, ".edb" will be added automatically.
• The dboptions can contain any of the options detailed below. These can be given as a single string of the form "option=value, option=value, ..." or as as sequence containing option-value pairs, { {option,value}, {option,value}, ... } Note: The options can be in any order.
• The options are...
  • LOCK_METHOD : an integer specifying which type of access can be granted to the database. This must be one of DB_LOCK_NO, DB_LOCK_EXCLUSIVE, DB_LOCK_SHARDED or DB_LOCK_READ_ONLY.
  • 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.
• If a symbolic name has already been defined for a database, you can get it's full path and options by calling this function with dboptions set to CONNECTION. The returned value is a sequence of two elements. The first is the full path name and the second is a list of the option values. These options are indexed by [CONNECT_LOCK], [CONNECT_TABLES], and [CONNECT_FREE].
• If a symbolic name has already been defined for a database, you remove the symbolic name by calling this function with dboptions set to DISCONNECT.

Example 1:

db_connect("myDB", "/usr/data/myapp/customer.edb", {{LOCK_METHOD,DB_LOCK_NO},
                                                            {INIT_TABLES,1}})
db_open("myDB")

Example 2:

db_connect("myDB", "/usr/data/myapp/customer.edb",
                          sprintf("init_tables=1,lock_method=%d",DB_LOCK_NO))
db_open("myDB")

Example 3:

db_connect("myDB", "/usr/data/myapp/customer.edb",
                          sprintf("init_tables=1,lock_method=%d",DB_LOCK_NO))
db_connect("myDB",,CONNECTION) --> {"/usr/data/myapp/customer.edb", {0,1,1}}
db_connect("myDB",,DISCONNECT) -- The name 'myDB' is removed from EDS.

See Also:

db_create, db_open, db_select

8.28.8.2 db_create

include std/eds.e
namespace eds
public function db_create(sequence path, integer lock_method = DB_LOCK_NO,
        integer init_tables = DEF_INIT_TABLES,
        integer init_free = DEF_INIT_FREE)

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

Parameters:

1. path : a sequence, the path to the file that will contain the database.
2. 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).
3. init_tables : an integer giving the initial number of tables to reserve space for. The default is 5 and the minimum is 1.
4. 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 file in the path does not have an extention, ".edb" 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

8.28.8.3 db_open

include std/eds.e
namespace eds
public function db_open(sequence path, integer lock_method = DB_LOCK_NO)

Open an existing Euphoria database.

Parameters:

1. path : a sequence, the path to the file containing the database
2. lock_method : an integer specifying which sort of access can be granted to the database. The types of lock that you can use are:
   1. DB_LOCK_NO : (no lock) - The default
   2. DB_LOCK_SHARED : (shared lock for read-only access)
   3. 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 WINDOWS 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

8.28.8.4 db_select

include std/eds.e
namespace eds
public function db_select(sequence path, integer lock_method = - 1)

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

Parameters:

1. path : a sequence, the path to the database to be the new current database.
2. 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

8.28.8.5 db_close

include std/eds.e
namespace eds
public procedure db_close()

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.

8.28.9 Managing tables

8.28.9.1 db_select_table

include std/eds.e
namespace eds
public function db_select_table(sequence name)

Parameters:

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

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

8.28.9.2 db_current_table

include std/eds.e
namespace eds
public function db_current_table()

Get name of currently selected table

Parameters:

1. 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

8.28.9.3 db_create_table

include std/eds.e
namespace eds
public function db_create_table(sequence name, integer init_records = DEF_INIT_RECORDS)

Create a new table within the current database.

Parameters:

1. name : a sequence, the name of the new table.
2. 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

8.28.9.4 db_delete_table

include std/eds.e
namespace eds
public procedure db_delete_table(sequence name)

Delete a table in the current database.

Parameters:

1. 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

8.28.9.5 db_clear_table

include std/eds.e
namespace eds
public procedure db_clear_table(sequence name, integer init_records = DEF_INIT_RECORDS)

Clears a table of all its records, in the current database.

Parameters:

1. name : a sequence, the name of the table to clear.

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 this is the current table, after this operation it will still be the current table.

See Also:

db_table_list, db_select_table, db_delete_table

8.28.9.6 db_rename_table

include std/eds.e
namespace eds
public procedure db_rename_table(sequence name, sequence new_name)

Rename a table in the current database.

Parameters:

1. name : a sequence, the name of the table to rename
2. new_name : a sequence, the new name for the table

Errors:

• An error occurs if the current database is not defined.
• If name does not exist on the current database, or if new_name does exist on the current database, an error will occur.

Comments:

The table to be renamed can be the current table, or some other table in the current database.

See Also:

db_table_list

8.28.9.7 db_table_list

include std/eds.e
namespace eds
public function db_table_list()

Lists all tables on the current database.

Returns:

A sequence, of all the table names in the current database. Each element of this sequence is a sequence, the name of a table.

Errors:

An error occurs if the current database is undefined.

Example 1:

sequence names = db_table_list()
for i = 1 to length(names) do
    puts(1, names[i] & '\n')
end for

See Also:

db_select_table, db_create_table

8.28.10 Managing Records

8.28.10.1 db_find_key

include std/eds.e
namespace eds
public function db_find_key(object key, object table_name = current_table_name)

Find the record in the current table with supplied key.

Parameters:

1. key : the identifier of the record to be looked up.
2. table_name : optional name of table to find key in

Returns:

An integer, either greater or less than zero:

• If above zero, the record identified by key was found on the current table, and the returned integer is its record number.
• If less than zero, the record was not found. The returned integer is the opposite of what the record number would have been, had the record been found.
• If equal to zero, an error occured.

Errors:

If the current table is not defined, it returns 0.

Comments:

A fast binary search is used to find the key in the current table. The number of comparisons is proportional to the log of the number of records in the table. The key is unique--a table is more like a dictionary than like a spreadsheet.

You can select a range of records by searching for the first and last key values in the range. If those key values don't exist, you'll at least get a negative value showing io:where they would be, if they existed. e.g. Suppose you want to know which records have keys greater than "GGG" and less than "MMM". If -5 is returned for key "GGG", it means a record with "GGG" as a key would be inserted as record number 5. -27 for "MMM" means a record with "MMM" as its key would be inserted as record number 27. This quickly tells you that all records, >= 5 and < 27 qualify.

Example 1:

rec_num = db_find_key("Millennium")
if rec_num > 0 then
    ? db_record_key(rec_num)
    ? db_record_data(rec_num)
else
    puts(2, "Not found, but if you insert it,\n")

    printf(2, "it will be #%d\n", -rec_num)
end if

See Also:

db_insert, db_replace_data, db_delete_record, db_get_recid

8.28.10.2 db_insert

include std/eds.e
namespace eds
public function db_insert(object key, object data, object table_name = current_table_name)

Insert a new record into the current table.

Parameters:

1. key : an object, the record key, which uniquely identifies it inside the current table
2. data : an object, associated to key.
3. table_name : optional table name to insert record into

Returns:

An integer, either DB_OK on success or an error code on failure.

Comments:

Within a table, all keys must be unique. db_insert() will fail with DB_EXISTS_ALREADY if a record already exists on current table with the same key value.

Both key and data can be any Euphoria data objects, atoms or sequences.

Example 1:

if db_insert("Smith", {"Peter", 100, 34.5}) != DB_OK then
    puts(2, "insert failed!\n")
end if

See Also:

db_delete_record

8.28.10.3 db_delete_record

include std/eds.e
namespace eds
public procedure db_delete_record(integer key_location, object table_name = current_table_name)

Delete record number key_location from the current table.

Parameter:

1. key_location : a positive integer, designating the record to delete.
2. table_name : optional table name to delete record from.

Errors:

If the current table is not defined, or key_location is not a valid record index, an error will occur. Valid record indexes are between 1 and the number of records in the table.

Example 1:

db_delete_record(55)

See Also:

db_find_key

8.28.10.4 db_replace_data

include std/eds.e
namespace eds
public procedure db_replace_data(integer key_location, object data,
        object table_name = current_table_name)

In the current table, replace the data portion of a record with new data.

Parameters:

1. key_location: an integer, the index of the record the data is to be altered.
2. data: an object , the new value associated to the key of the record.
3. table_name: optional table name of record to replace data in.

Comments:

key_location must be from 1 to the number of records in the current table. data is an Euphoria object of any kind, atom or sequence.

Example 1:

db_replace_data(67, {"Peter", 150, 34.5})

See Also:

db_find_key

8.28.10.5 db_table_size

include std/eds.e
namespace eds
public function db_table_size(object table_name = current_table_name)

Get the size (number of records) of the default table.

Parameters:

1. table_name : optional table name to get the size of.

Returns An integer, the current number of records in the current table. If a value less than zero is returned, it means that an error occured.

Errors:

If the current table is undefined, an error will occur.

Example 1:

-- look at all records in the current table
for i = 1 to db_table_size() do
    if db_record_key(i) = 0 then
    	puts(1, "0 key found\n")
    	exit
    end if
end for

See Also:

db_replace_data

8.28.10.6 db_record_data

include std/eds.e
namespace eds
public function db_record_data(integer key_location, object table_name = current_table_name)

Returns the data in a record queried by position.

Parameters:

1. key_location : the index of the record the data of which is being fetched.
2. table_name : optional table name to get record data from.

Returns:

An object, the data portion of requested record.
NOTE This function calls fatal() and returns a value of -1 if an error prevented the correct data being returned.

Comments:

Each record in a Euphoria database consists of a key portion and a data portion. Each of these can be any Euphoria atom or sequence.

Errors:

If the current table is not defined, or if the record index is invalid, an error will occur.

Example 1:

puts(1, "The 6th record has data value: ")
? db_record_data(6)

See Also:

db_find_key, db_replace_data

8.28.10.7 db_fetch_record

include std/eds.e
namespace eds
public function db_fetch_record(object key, object table_name = current_table_name)

Returns the data for the record with supplied key.

Parameters:

1. key : the identifier of the record to be looked up.
2. table_name : optional name of table to find key in

Returns:

An integer,

• If less than zero, the record was not found. The returned integer is the opposite of what the record number would have been, had the record been found.
• If equal to zero, an error occured. A sequence, the data for the record.

Errors:

If the current table is not defined, it returns 0.

Comments:

Each record in a Euphoria database consists of a key portion and a data portion. Each of these can be any Euphoria atom or sequence. NOTE This function does not support records that data consists of a single non-sequence value. In those cases you will need to use db_find_key and db_record_data.

Example 1:

printf(1, "The record['%s'] has data value:\n", {"foo"})
? db_fetch_record("foo")

See Also:

db_find_key, db_record_data

8.28.10.8 db_record_key

include std/eds.e
namespace eds
public function db_record_key(integer key_location, object table_name = current_table_name)

Parameters:

1. key_location : an integer, the index of the record the key is being requested.
2. table_name : optional table name to get record key from.

Returns An object, the key of the record being queried by index.
NOTE This function calls fatal() and returns a value of -1 if an error prevented the correct data being returned.

Errors:

If the current table is not defined, or if the record index is invalid, an error will occur.

Comments:

Each record in a Euphoria database consists of a key portion and a data portion. Each of these can be any Euphoria atom or sequence.

Example 1:

puts(1, "The 6th record has key value: ")
? db_record_key(6)

See Also:

db_record_data

8.28.10.9 db_compress

include std/eds.e
namespace eds
public function db_compress()

Compresses the current database.

Returns:

An integer, either DB_OK on success or an error code on failure.

Comments:

The current database is copied to a new file such that any blocks of unused space are eliminated. If successful, the return value will be set to DB_OK, and the new compressed database file will retain the same name. The current table will be undefined. As a backup, the original, uncompressed file will be renamed with an extension of .t0 (or .t1, .t2, ..., .t99). In the highly unusual case that the compression is unsuccessful, the database will be left unchanged, and no backup will be made.

When you delete items from a database, you create blocks of free space within the database file. The system keeps track of these blocks and tries to use them for storing new data that you insert. db_compress() will copy the current database without copying these free areas. The size of the database file may therefore be reduced. If the backup filenames reach .t99 you will have to delete some of them.

Example 1:

if db_compress() != DB_OK then
    puts(2, "compress failed!\n")
end if

8.28.10.10 db_current

include std/eds.e
namespace eds
public function db_current()

Get name of currently selected database.

Parameters:

1. None.

Returns:

A sequence, the name of the current database. An empty string means that no database is currently selected.

Comments:

The actual name returned is the path as supplied to the db_open routine.

Example 1:

s = db_current_database()

See Also:

db_select

8.28.10.11 db_cache_clear

include std/eds.e
namespace eds
public procedure db_cache_clear()

Forces the database index cache to be cleared.

Parameters:

None

Comments:

• This is not normally required to the run. You might run it to set up a predetermined state for performance timing, or to release some memory back to the application.

Example 1:

db_cache_clear() -- Clear the cache.

8.28.10.12 db_set_caching

include std/eds.e
namespace eds
public function db_set_caching(atom new_setting)

Sets the key cache behavior.
Initially, the cache option is turned on. This means that when possible, the keys of a table are kept in RAM rather than read from disk each time db_select_table() is called. For most databases, this will improve performance when you have more than one table in it.

Parameters:

1. integer : 0 will turn of caching, 1 will turn it back on.

Returns:

An integer, the previous setting of the option.

Comments:

When caching is turned off, the current cache contents is totally cleared.

Example 1:

x = db_set_caching(0) -- Turn off key caching.

8.28.10.13 db_replace_recid

include std/eds.e
namespace eds
public procedure db_replace_recid(integer recid, object data)

In the current database, replace the data portion of a record with new data. This can be used to quickly update records that have already been located by calling db_get_recid. This operation is faster than using db_replace_data

Parameters:

1. recid : an atom, the recid of the record to be updated.
2. data : an object, the new value of the record.

Comments:

• recid must be fetched using db_get_recid first.
• data is an Euphoria object of any kind, atom or sequence.
• The recid does not have to be from the current table.
• This does no error checking. It assumes the database is open and valid.

Example 1:

rid = db_get_recid("Peter")
rec = db_record_recid(rid)
rec[2][3] *= 1.10
db_replace_recid(rid, rec[2])

See Also:

db_replace_data, db_find_key, db_get_recid

8.28.10.14 db_record_recid

include std/eds.e
namespace eds
public function db_record_recid(integer recid)

Returns the key and data in a record queried by recid.

Parameters:

1. recid : the recid of the required record, which has been previously fetched using db_get_recid.

Returns:

An sequence, the first element is the key and the second element is the data portion of requested record.

Comments:

• This is much faster than calling db_record_key and db_record_data.
• This does no error checking. It assumes the database is open and valid.
• This function does not need the requested record to be from the current table. The recid can refer to a record in any table.

Example 1:

rid = db_get_recid("SomeKey")
? db_record_recid(rid)

See Also:

db_get_recid, db_replace_recid

8.28.10.15 db_get_recid

include std/eds.e
namespace eds
public function db_get_recid(object key, object table_name = current_table_name)

Returns the unique record identifier (recid) value for the record.

Parameters:

1. key : the identifier of the record to be looked up.
2. table_name : optional name of table to find key in

Returns:

An atom, either greater or equal to zero:

• If above zero, it is a recid.
• If less than zero, the record wasn't found.
• If equal to zero, an error occured.

Errors:

If the table is not defined, an error is raised.

Comments:

A recid is a number that uniquely identifies a record in the database. No two records in a database has the same recid value. They can be used instead of keys to quickly refetch a record, as they avoid the overhead of looking for a matching record key. They can also be used without selecting a table first, as the recid is unique to the database and not just a table. However, they only remain valid while a database is open and so long as it doesn't get compressed. Compressing the database will give each record a new recid value.

Because it is faster to fetch a record with a recid rather than with its key, these are used when you know you have to refetch a record.

Example 1:

rec_num = db_get_recid("Millennium")
if rec_num > 0 then
    ? db_record_recid(rec_num) -- fetch key and data.
else
    puts(2, "Not found\n")
end if

See Also:

db_insert, db_replace_data, db_delete_record, db_find_key