# OpenEuphoria Manual

## Euphoria v4.1

routine or constant name search

| Up |  |  | TOC | Index
<< 7 Included Tools | < 8.28 Statistics | Up: 8 API Reference | 8.30 Prime Numbers > | 9 Release Notes >>

## 8.29 Euphoria Database (EDS)

### 8.29.1 Error Status Constants

#### 8.29.1.1 DB_OK

    include std/eds.e
    namespace eds
    public enum DB_OK

Database is OK, not error has occurred.

#### 8.29.1.2 DB_OPEN_FAIL

    include std/eds.e
    namespace eds
    public enum DB_OPEN_FAIL

The database could not be opened.

#### 8.29.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.29.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.29.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.29.1.6 DB_FATAL_FAIL

    include std/eds.e
    namespace eds
    public enum DB_FATAL_FAIL

A fatal error has occurred.

### 8.29.2 Lock Type Constants

#### 8.29.2.1 DB_LOCK_NO

    include std/eds.e
    namespace eds
    public enum DB_LOCK_NO

Do not lock the file.

#### 8.29.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.29.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.29.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.29.3 Error Code Constants

#### 8.29.3.1 MISSING_END

    include std/eds.e
    namespace eds
    public enum MISSING_END

Missing 0 terminator

#### 8.29.3.2 NO_DATABASE

    include std/eds.e
    namespace eds
    public enum NO_DATABASE

current_db is not set

#### 8.29.3.3 BAD_SEEK

    include std/eds.e
    namespace eds
    public enum BAD_SEEK

`io:seek` failed.

#### 8.29.3.4 NO_TABLE

    include std/eds.e
    namespace eds
    public enum NO_TABLE

no table was found.

#### 8.29.3.5 DUP_TABLE

    include std/eds.e
    namespace eds
    public enum DUP_TABLE

this table already exists.

#### 8.29.3.6 BAD_RECNO

    include std/eds.e
    namespace eds
    public enum BAD_RECNO

unknown key_location index was supplied.

#### 8.29.3.7 INSERT_FAILED

    include std/eds.e
    namespace eds
    public enum INSERT_FAILED

could not insert a new record.

#### 8.29.3.8 LAST_ERROR_CODE

    include std/eds.e
    namespace eds
    public enum LAST_ERROR_CODE

last error code

#### 8.29.3.9 BAD_FILE

    include std/eds.e
    namespace eds
    public enum BAD_FILE

bad file

### 8.29.4 Indexes for Connection Option Structure.

#### 8.29.4.1 CONNECT_LOCK

    include std/eds.e
    namespace eds
    public enum CONNECT_LOCK

Locking method

#### 8.29.4.2 CONNECT_TABLES

    include std/eds.e
    namespace eds
    public enum CONNECT_TABLES

Initial number of tables to create

#### 8.29.4.3 CONNECT_FREE

    include std/eds.e
    namespace eds
    public enum CONNECT_FREE

Initial number of free pointers to create

### 8.29.5 Database Connection Options

#### 8.29.5.1 DISCONNECT

    include std/eds.e
    namespace eds
    public constant DISCONNECT

Disconnect a connected database

#### 8.29.5.2 LOCK_METHOD

    include std/eds.e
    namespace eds
    public constant LOCK_METHOD

Locking method to use

#### 8.29.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.29.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.29.5.5 CONNECTION

    include std/eds.e
    namespace eds
    public constant CONNECTION

Fetch the details about the alias

### 8.29.6 Variables

#### 8.29.6.1 db_fatal_id

    include std/eds.e
    namespace eds
    public integer db_fatal_id

This is an Exception handler.

Set this to a valid routine_id value for a procedure that will be called whenever the library detects a serious error. Your 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.29.7 Routines

#### 8.29.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 not 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.29.7.2 db_dump

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

prints 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.29.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.29.8 Managing Databases

#### 8.29.8.1 db_connect

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

defines 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.29.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)

creates 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.29.8.3 db_open

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

opens 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 and 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.29.8.4 db_select

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

chooses 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.29.8.5 db_close

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

unlocks and closes 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.29.9 Managing Tables

#### 8.29.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.29.9.2 db_current_table

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

gets the 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.29.9.3 db_create_table

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

creates 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 zero 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.29.9.4 db_delete_table

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

deletes 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.29.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.29.9.6 db_rename_table

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

renames 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.29.9.7 db_table_list

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

lists all tables in 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.29.10 Managing Records

#### 8.29.10.1 db_find_key

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

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

For example, 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.29.10.2 db_insert

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

inserts 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_replace_data, db_delete_record

#### 8.29.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)

deletes record number `key_location` from the current table.

##### Parameters:

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.29.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)

replaces, the current table, 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.29.10.5 db_table_size

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

gets 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.29.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.29.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.29.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)

returns the key of a record given an index.

##### 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.29.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.29.10.10 db_current

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

gets 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.29.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:

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

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

sets the key cache behavior.

##### Parameters:

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

##### Returns:

An integer, the previous setting of the option.

##### Comments:

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.

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

##### Example 1:

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

#### 8.29.10.13 db_replace_recid

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

replaces, in the current database, the data portion of a record with new 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:

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

- `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.29.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.29.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 does not 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

| Up |  |  | TOC | Index
<< 7 Included Tools | < 8.28 Statistics | Up: 8 API Reference | 8.30 Prime Numbers > | 9 Release Notes >>