Этот документ описывает процедуры и функции низкого уровня ESDB, экспортируемые модулем database.pas, которые базируются на ESDB-API уровня TCP/IP. Информация, представленная здесь, может быть полезной стронним разработчикам для создания ними собственных модулей и компонент, работающих с ESDB. Примеры использования описанных в этом документе функций можно видеть в файле table.pas.

function CreateDatabase(const DatabaseName,ServerAddress:String; const ServerPort:Integer):Boolean;

Эта функция предназначена для создания новой базы данных. В качестве параметров она принимает имя создаваемой базы данных (включая полный путь со всеми необходимыми подкаталогами), имя сервера, на котором требуется создать базу данных и номер TCP-порта, на котором принимает вызовы служба ESDB на соответствующем сервере. Функция возвращает результат логического типа: true - если базу данных создать удалось, и false - в противном случае. Выполнение этой функции может быть неудачным в следующих случаях:

• неправильно указано имя сервера или номер порта
• на указанной машине не активен сервер ESDB
• полный путь содержит имена несуществующих каталогов (сервер ESDB не занимается их созданием, все необходимые подкаталоги должны быть созданы заблаговременно)
• указанная база данных уже существует

function DropDatabase(const DatabaseName,ServerAddress:String; const ServerPort:Integer):Boolean;

Эта функция предназначена безвозвратного уничтожения ранее созданной базы данных. В качестве параметров она принимает имя удаляемой базы данных (включая полный путь со всеми подкаталогами), имя сервера, на котором требуется уничтожить базу данных и номер TCP-порта, на котором принимает вызовы служба ESDB на соответствующем сервере. Функция возвращает результат логического типа: true - если базу данных удалось уничтожить, и false - в противном случае. Выполнение этой функции может быть неудачным в следующих случаях:

• неправильно указано имя сервера или номер порта
• на указанной машине не активен сервер ESDB
• неверно указано имя базы данных или она не существует
• указанная база данных используется каким-то клиентом (к ней есть активные в данный момент подключения)

function Open(const DatabaseName,ServerAddress:String; const ServerPort:Integer):Boolean;

Эта функция открывает ранее созданную (то есть существующую) базу данных. В качестве параметров она принимает имя открываемой базы данных (включая полный путь со всеми подкаталогами), имя сервера, на котором требуется открыть базу данных и номер TCP-порта, на котором принимает вызовы служба ESDB на соответствующем сервере. Функция возвращает результат логического типа: true - если базу данных удалось открыть, и false - в противном случае. Успешное открытие любой базы данных необходимо для работы с размещенными в ней таблицами и должно предшествовать любой такой работе. Выполнение этой функции может быть неудачным в следующих случаях:

• неправильно указано имя сервера или номер порта
• на указанной машине не активен сервер ESDB
• неверно указано имя базы данных или она не существует

procedure Close;

Эта процедура закрывает ранее открытую функцией Open базу данных. Она не имеет параметров и ничего не возвращает. Если база данных действительно была открыта, то данная процедура ее закрывает, если база данных не была перед этим открыта, то эта процедура ничего не делает (и аварийной ситуации это не вызовет). Перед закрытием базы данных желательно закрыть ранее открытые в рамках этого подключения таблицы, однако реальной нужды в этом нет, так как сервер ESDB и сам в этом случае все корректно закроет, так что никакой потери или искажения данных (равно как и индексов) не произойдет. Также следует отметить, что этот метод автоматически вызывается процедурой Free класса TDatabase, так что уничтожение любого объекта этого класса также сопровождается аккуратным закрытием любого активного соединения с сервером ESDB, если таковое имело место.

function CreateTable(const TableName:String; const FieldsList:TESDBFieldsList):Boolean;

Эта функция создает в открытой ранее базе данных новую таблицу. В качестве параметров она принимает имя создаваемой таблицы и спецификацию ее полей в формате TESDBFieldsList. Функция возвращает результат логического типа: true - если таблицу удалось создать, и false - в противном случае. Выполнение этой функции может быть неудачным в следующих случаях:

• на момент вызова соединение с базой данных не установлено
• таблица с указанным именем в текущей базе данных уже существует

function OpenTable(const TableName:String):HTABLE;

Эта функция открывает в текущей базе данных существующую там таблицу. В качестве параметра она принимает имя открываемой таблицы. Функция возвращает указатель на открытую таблицу типа HTABLE, который используется в дальнейшем при операциях чтения и записи с этой таблицей. В случае успеха, возвращаемое значение будет больше нуля, а при неудаче - это будет отрицательный код ошибки (описание кодов ошибок находится в файле common.pas). Выполнение этой функции может быть неудачным в следующих случаях:

• на момент вызова соединение с базой данных не установлено
• таблицы с указанным именем в текущей базе данных не существует

procedure CloseTable(const hTable:HTABLE);

Эта процедура закрывает ранее открытую функцией OpenTable таблицу. В качестве единственного параметра ей передается указатель на ранее открытую функцией OpenTable таблицу, подлежащую закрытию. При передаче этой процедуре недействительного указателя, аварийная ситуация не возникает, и в этом случае данная процедура просто ничего не делает.

function PackTable(const hTable:HTABLE):Boolean;

Эта функция пакует ранее открытую функцией OpenTable таблицу. В качестве единственного параметра ей передается указатель на ранее открытую функцией OpenTable таблицу, подлежащую упаковке. Суть процесса упаковки заключается в перемещении записей в таблице, так что в первый момент после этого вызова в таблице нет ни одной удаленной записи, и таблица, таким образом, компактно занимает в базе данных минимально возможное пространство. Выполнение этого вызова производится сервером ESDB в три этапа:

1. сервер ESDB пытается установить монопольный режим использования данной таблицы
2. сервер ESDB пакует данную таблицу (одновременно корректируя при этом все ее индексы)
3. сервер ESDB отменяет монопольный режим использования данной таблицы

Таким образом, устанавливать монопольный режим использования таблицы клиентской части самой не нужно - сервер выполняет это автоматически. При неудаче на этапе 1 выполнение этапов 2 и 3 не производится, и выполнение вызова считается неудачным. Функция возвращает результат логического типа: true - если таблицу удалось упаковать, и false - в противном случае. Следует отметить, что модули сторонних разработчиков, при удачном окончании этого вызова, должны тут же переинициализировать у себя параметры таблицы, так как текущая запись становится недействительной, изменяется полное количество записей и т.п. Выполнение этой функции может быть неудачным в следующих случаях:

• на момент вызова соединение с базой данных не установлено
• передан недействительный указатель на таблицу (аварийной ситуации это не вызывает)
• к данной таблице не удалось получить монопольного доступа (то есть имеются подключения к ней из других сессий)