Диплом К

3.4.7.1. Конструктор создания ВТ–файла

btFile	(word	wPageLen,
	char*	lpszFileName,
	byte	bDepthStack	= tbFILE_SIZE_STACK,
	char*	lpUserArea	= NULL,
	word	wMode	= btFILE_MODE_OPEN,
	word	wSizeCaсhe	= btFILE_SIZE_CACHE,
	byte	bSavePool	= btFILE_SAVE_POOL)

Данный конструктор предназначен для создания нового ВТ–файла. Параметры конструктора:

wPageLen – размер страницы DS–файла, в котором будут храниться блоки индек-

сов. Может принимать значения от 256 до 8096. Максимальный размер блока индекса определяется числом байт данных, вмещающихся на одну страницу DS-файла, поэтому варьируя этим параметром можно существенно менять временные характеристики и объемы расходуемой оперативной памяти при работе.

lpszFileName – имя файла для размещения ВТ-файла.

bDepthStack – глубина стека открытых индексов – максимальное число одновре-

менно открытых индексов в рамках ВТ-файла. Задание значения 0 все равно приведет к наличию стека глубиной 1. Этот параметр сильно влияет, как на скорость работы (осо-

бенно при одновременной модификации в нескольких индексах) так и на объем расхо-

дуемой оперативной памяти.

lpUserArea – адрес данных пользователя для помещения в область пользователя при ВТ-файла. Длина этой области байт, так как используется область DS-файла, пред-

назначенная для этой цели.

wMode – режимы работы с ВТ-файлом в данном сеансе. Без изменения передается конструктору DS-файла. Описание возможных флагов приведено в разделе 3.3.4.1.

wSizeCache – размер кэша DS-файла в страницах. Описание этого параметра при-

ведено в разделе 3.3.4.1.

wSavePool – размер пула DS-файла в строках Описание этого параметра приведе-

но в разделе 3.3.4.1.

Создает ВТ–файл с именем lpszFileName (если существует, то перезаписывает),

формирует пустой каталог индексов и помещает его в файл как запись.

3.4.7.2. Конструктор открытия ВТ–файла

btFile	(char*	lpszFileName,
	byte	bDepthStack	= btFILE_SIZE_STACK,
	word	wMode	= btFILE_MODE_OPEN,
	word	wSizeCache	= tbFILE_SIZE_CACHE,
	byte	bSavePool	= btFILE_SAVE_POOL)

Данный конструктор предназначен для открытия уже существующего ВТ–файла.

При отсутствии файла с заданным именем будет зафиксирована ошибка dsPage_ErrFName. Все параметры имеют то же самое значение, что и при создании ВТ– файла.

При открытии считывается каталог индексов, но ни один индекс не открывается.

3.4.7.3. Добавление дерева в ВТ–файл

byte AddTree	(char*	lpszNameTree,
	byte	bKeyType	= btKEY_STRING,
	byte	bValType	= btVAL_NUMBER,
	byte	bFixLenKey	= 0,
	byte	bFixLenVal	= 0,
	byte	bUniqKey	= btNOT_UNIQ_KEY)

Метод добавляет новый индекс в каталог ВТ–файла. Параметры метода описаны ниже:

lpszNameTree – имя индекса (длиной до 8 символов, остальные символы обреза-

ются). Это имя должно быть уникальным в рамках индексного файла, иначе будет за-

фиксирована ошибка.

bKeyType – тип ключа, может принимать одно из значений btKEY_xxx (см. табл.

5). Если этот параметр имеет значение btKEY_USER_TYPE, то необходимо задание функции сравнения ключей, кроме того обязательно задание не нулевого значения па-

раметра bFixLenKey.

bValType – тип значения, может принимать одно из значений btVAL_xxx (см.

табл. 6). Если этот параметр имеет значение btVAL_USER_TYPE, то необходимо зада-

ние функции сравнения ключей, кроме того обязательно задание не нулевого значения параметра bFixLenVal.

bFixLenKey – длина ключа в байтах. Этот параметр необходимо задавать только для ключей типа btKEY_STRING и btKEY_USER_TYPE, для всех остальных типов ключей этот параметр берется из внутренней таблицы и задание его не требуется.

bFixLenVal – длина значения в байтах. Этот параметр необходимо задавать только для значений типа btVAL_STRING, btVAL_NUMBER и btVAL_USER_TYPE, для всех остальных типов значений этот параметр берется из внутренней таблицы и задание его не требуется.

bUniqKey – признак хранения в индексе уникальных ключей. В таком индексе при каждом ключе может находиться только одно значение, что упрощает внутренние структуры и приводит к уменьшению объема индекса и улучшению временных харак-

теристик.

Возвращает: номер добавленного индекса

3.4.7.4. Удаление дерева в ВТ–файл

void DelTree (byte bNumTree)

Удаляет из индексного файла индекс с заданным номером. При удалении индекса из индексного файла удаляются все блоки, принадлежащие удаляемому индексу, затем из каталога удаляется описатель удаляемого индекса. Если удаляемый индекс был от-

крыт (есть в стеке), то освобождается оперативная память, занятая под блоки пути этого индекса. Номер удаленного индекса становится “свободным” и, впоследствии, может быть присвоен вновь создаваемым в этом индексном файле индексам. Параметр метода:

bNumTree – номер удаляемого индекса.

3.4.7.5. Добавление пары ключ–значение

void Add	(char*	lpKey,
	char*	lpVal,
	byte	bNumTree)

Добавляет в заданный индекс заданную пару ключ:значение. Если эта пара уже существует, то добавление не производится и фиксируется ошибка. Если существует

добавляемый ключ, то добавляется только значение в список значений при ключе. Если ключ не существует, то в индекс добавляется и ключ и значение. Параметры:

lpKey – адрес добавляемого ключа (формат зависит от типа ключей в индексе). lpVal – адрес значения, добавляемого к ключу (формат зависит от типа значений в

индексе).

bNumTree – номер индекса, куда производить добавление.

3.4.7.6. Удаление пары ключ–значение

void Del	(char*	lpKey,
	char*	lpVal,
	byte	bNumTree,
	byte	bLenVal	= 0)

Производит удаление из заданного индекса заданной пары ключ:значение. Если такой пары нет, то фиксируется ошибка. Если удаляемое значение при ключе един-

ственное, то удаляется и ключ и значение, в противном случае удаляется только значе-

ние из списка значений при ключе. Если после операции удаления какой-либо блок ин-

декса окажется пустым, то он будет удален из файла, хранящего блоки индексов. Если значение параметра bLenVal меньше длины значений в индексе, то будет удалено пер-

вое подходящее значение. Параметры:

lpKey – адрес удаляемого ключа (формат зависит от типа ключей в индексе). lpVal – адрес значения, удаляемого у ключа (формат зависит от типа значений в

индексе).

bNumTree – номер индекса, где производить удаление.

bLenVal – длина для сравнения при поиске удаляемого значения (может прини-

мать значение от 0 до длины значений в индексе). Значение по умолчанию задает срав-

нение по всей длине значения.

3.4.7.7. Поиск ключа на полное совпадение

btFind* FindEqu	(char*	lpKey,
	byte	bNumTree,
	byte&	rbResult)

Проводит поиск на полное совпадение заданного ключа среди всех ключей в за-

данном индексе. В rbResult могут возвращаться следующие значения:

0 – обнаружено полное совпадение искомого ключа с ключом в индексе;

1 – полного совпадения нет, но обнаружено вхождение искомого ключа в ключ индекса (совпадение с началом ключа);

2 – искомый ключ вообще не найден, но должен быть между ключами индекса;

3 – искомый ключ больше самого большого ключа индекса.

Метод возвращает адрес созданного объекта результата поиска (класс btFind) в

индексе. Результат определен (не NULL) для любых значений rbResult, а NULL возвра-

щается только при ошибке внутри метода или при пустом индексе. При rbResult равном

0, результат поиска содержит список значений искомого ключа, для всех остальных значений rbResult результат поиска будет пуст. Параметры:

lpKey – адрес искомого ключа.

bNumTree – номер индекса, в котором проводить поиск. rbResult – код, уточняющий результат поиска.

3.4.7.8. Поиск по началу ключа

btFind* FindBegin (char* lpKey, byte bNumTree)

Проводит поиск ключей, начинающихся на искомый ключ или совпадающих с ним. В rbResult могут возвращаться следующие значения:

0 – обнаружено или полное совпадение или вхождение искомого ключа;

1 – искомый ключ вообще не найден, но должен быть между ключами индекса;

2 – искомый ключ больше самого большого ключа индекса.

Метод возвращает адрес созданного объекта результата поиска в индексе. Резуль-

тат определен (не NULL) для любых значений rbResult, а NULL возвращается только при ошибке внутри метода или при пустом индексе. При rbResult равном 0, результат поиска содержит список значений от всех ключей индекса, начинающихся на искомый ключ или совпадающих с ним, для всех остальных значений rbResult результат поиска будет пуст. Параметры:

lpKey – адрес искомого ключа.

bNumTree – номер индекса, где проводить поиск.

3.4.7.9. Поиск по интервалу ключей

Поиск в индексе в диапазоне ключей

btFind* FindRange (byte	bNumTree,
char*	lpKeyB	= NULL,
char*	lpKeyE	= NULL)

Проводит поиск ключей, входящих в заданный диапазон. Возвращает результат

поиска, содержащий список значений всех ключей, входящих в заданный диапазон. Ес-

ли в индексе нет ни одного такого ключа, то возвращается пустой результат. Если ин-

декс пуст, то возвращается NULL. Параметры:

bNumTree – номер индекса, где проводить поиск.

lpKeyB – адрес ключа, задающего начало диапазона (если NULL, то начало диапа-

зона будет выбрано по первому ключу индекса).

lpKeyE – адрес ключа, задающего конец диапазона (если NULL, то конец диапазо-

на будет выбран по последнему ключу индекса).

3.4.7.10. Поиск уникальных ключа

byte FindUniq	(char*	lpKey,
	char*	lpVal,
	byte	bNumTree)

Проводит поиск искомого ключа в заданном индексе с уникальными ключами.

Метод возвращает значение, уточняющее результат поиска:

0 – есть такой ключ (в lpVal копируется значение при этом ключе);

1 – искомого ключа нет, но есть ключ, начинающийся на него;

2 – искомого ключа нет, но он должен быть между ключами индекса;

3 – искомый ключ больше самого большого ключа индекса;

4 – индекс с заданным номером имеет не уникальные ключи;

5 – ошибка (см. код ошибки)

Параметры:

lpKey – адрес искомого ключа.

lpVal – адрес, где разместить значение при найденном ключе (память должна быть выделена размером под длину значений в индексе).

bNumTree – номер индекса, где проводить поиск.

3.4.8. Заключение Разработанная библиотека функций полностью соответствует техническому зада-

нию. Реализованы широкие возможности по управлению файлом индексов для базы данных.

Реализована возможность в одном индексном файле нескольких индексов для раз-

ных типов ключей, в том числе с переменной длиной ключа. Для каждого ключа воз-

можно хранение одного или нескольких значений. Выбранная структура представления индекса в виде модифицированных В+деревьев обеспечивает высокую скорость поиска.

Исследование скоростных характеристик библиотеки приведено в исследовательской части дипломной работы.

	Табл. 3. Список методов класса btFile
Название	Назначение
AbortTransaction	Аварийное завершение транзакции. Отмена всех сделанных
	в ходе транзакции изменений
Add	Добавление пары ключ–значение в заданный индекс
BeginTransaction	Начало транзакции в файле индексов
Clear	Очистка файла индексов. Все записи удаляются
ClearError	Сброс признака ошибки
Del	Удаление пары ключ–значение из заданного индекса
dsError	Обработка ошибки с уровня DS–файла
EndTransaction	Нормальное завершение транзакции
FindBegin	Поиск в заданном индексе по началу ключа
FindEqu	Поиск ключа на полное совпадение
FindRange	Поиск в заданном индексе по интервалу ключей
FindUniq	Поиск уникального ключа в индексе
Flush	Принудительная запись всех кэш–буферов на диск. Гаранти-
	рует, что все сделанные изменения запишутся на диск
GetFile	Вернуть указатель на DS–файл
Seek (вариант 1)	Позиционирование на заданную пару ключ–значение в за-
	данном индексе.
Seek (вариант 2)	Позиционирование на первую/послед-
	нюю/следующую/предыдущую пару ключ–значение
	в заданном индексе.
SetUserArea	Запоминает данные пользователя в поле User нулевой стра-
	ницы
UserArea	Возвращает пользовательские данные (поле User с нулевой
	страницы)

Табл. 4. Список регистрируемых классом btFile ошибок

Код ошибки	Описание ошибки
btBLOCK_BlockIsEmpty	Удаление из пустого блока
btBLOCK_DelBeforSearch	Не установлены текущие значений пе-
	ред удалением
btBLOCK_EmptyValList	Пуст список значений
btBLOCK_ErrorBinSearch	Ошибка в функции BinSearch
btBLOCK_GetKeyInvalidMode	Неверный режим позиционирования по
	ключам
btBLOCK_GetValInvalidMode	Неверный режим позиционирования по
	значениям
btBLOCK_InsertItemBeforSearch	Вставка перед поиском
btBLOCK_InsertRefBeforSearch	Не установлены текущие значений пе-
	ред вставкой
btBLOCK_InvalidDivArea	Неверный адрес области разбиений
btBLOCK_InvalidKey	Неверный ключ
btBLOCK_InvalidLenValue	Неверная длина значения при поиске
btBLOCK_InvalidNewItem	Неверный адрес нового элемента
btBLOCK_InvalidNewRef	Неверный адрес вставляемого элемента
btBLOCK_KeyNotFound	Искомый ключ меньше нулевого ключа
btBLOCK_NoMemory	Нехватка памяти
btBLOCK_NotSetCurVal	Не установлены текущие значений
btBLOCK_Overflow	Переполнение блока индекса
btCATALOG_ErrorCreateTree	Ошибка при создании индекса
btCATALOG_InvalidInfoMode	Неверный режим для справки
btCATALOG_InvalidNumTree	Неверный номер индекса
btCATALOG_InvalidTreeParameter	Ошибочные параметры для индекса
btCATALOG_NameTreeNotFound	Нет индекса с таким номером
btCATALOG_NoMemory	Нехватка памяти
btCATALOG_TreeAlreadyExist	Индекс уже существует

Код ошибки	Описание ошибки
btCTRLBLOCK_AddExistItem	Добавление существующего элемента
btCTRLBLOCK_BlockIsEmpty	Блок пуст
btCTRLBLOCK_DelBeforSearch	Удаление перед поиском
btCTRLBLOCK_GetRefInvalidMode	Неверный режим позиционирования
btCTRLBLOCK_InvalidNewItem	Неверный адрес нового элемента
btCTRLBLOCK_NoMemory	Нехватка памяти
btCTRLBLOCK_NotSetCurVal	Не установлены текущие значений
btCTRLBLOCK_Overflow	Переполнение
btFILE_dsError	Ошибка в DS-файле
btFILE_InvalidHead	Неверный заголовок файла
btFILE_InvalidLenCatalog	Неверная длина каталога в заголовке
btFILE_InvalidLenPage	Недопустимая длина страницы
btFILE_NoMemory	Нехватка памяти
btFILE_NotBTFile	Заданный файл не BT-файл
btFIND_InvalidSrcRes	Неверный операнд
btFIND_LenValNotEqu	Неравны длины значений операндов
btFIND_NoMemory	Нехватка памяти
btFIND_NotCreateFile	Ошибка при создании файла свопинга
btFIND_UnknowCodeOp	Неопознанный код операции
btOK	Нет ошибки (O'кей)
btRESBLOCK_BlockIsEmpty	Блок пуст
btRESBLOCK_ErrorBinSearch	Ошибка в функции BinSearch
btRESBLOCK_GetValInvalidMode	Неверный режим позиционирования
btRESBLOCK_InsertBeforSearch	Вставка перед поиском
btRESBLOCK_InvalidAddItem	Неверный элемент для добавления
btRESBLOCK_InvalidTruncLen	Неверная длина при усечении
btRESBLOCK_InvalidValue	Неверное значение
btRESBLOCK_NoMemory	Нехватка памяти
btRESBLOCK_NotSetCurVal	Не установлены текущие значений
btRESBLOCK_Overflow	Переполнение