Sources
Delphi Russian Knowledge Base
DRKB - это самая большая и удобная в использовании база знаний по Дельфи в рунете, составленная Виталием Невзоровым

Использованию в Delphi прямых обращений к ядру Btrieve

01.01.2007

Введение. Данный документ - краткая инструкция по использованию в DELPHI прямых обращений к ядру CУБД Btrieve, написанная для людей с SQL-мышлением, которым судьба-индейка подсунула свинью в виде производственной необходимости временно (или, не дай Создатель, постоянно) использовать это чудо Pervasive-вской мысли. Мне самому пришлось долго и больно перестраиваться с незамутненных SQL-понятий работы с данными на суровую логику программирования более низкого уровня. Данная шпаргалка призвана облегчить этот процесс, и содержит параллели между основными SQL-командами (select/insert/update/delete) и вызовами функции BTRVID, описанной по принципу "черного ящика". Сразу скажу, что не являюсь специалистом по Btrievу (т.е. могу путаться в Btrievовских терминах), большая часть информации получена эмпирическим путем, все примеры использовались в жизни, отлажены и работают.

Отдельно замечу следующее. Вообще говоря, в природе существует Pervasive ODBC, его заменитель Titan Btrieve, и, возможно, кое-что еще, что позволяет обращаться к Btrieve-данным через SQL-запросы. Однако во-первых, это дело работает на порядок медленнее, а во-вторых, в определенных ситуациях (например в моей - мне пришлось организовывать перекачку данных из Informix SQL-сервера в программу "Парус", использующую Btrieve. С Informixом, сами понимаете, никаких проблем не было) из-за специфического формата данных, определяемого конкретным программным продуктом, использование ODBC порой оказывается в принципе невозможным. Например, его (ODBC) приводят в смятение нулевые байты в текстовых полях. И последнее. По правильному, для работы с Btrievом нужно устанавливать Btrievовский Engine, пытаться добиться от него стабильной работы, поганить реестр и все такое. (Может, конечно, это со мной что-то не так, но мне пришлось через это пройти. Хотя на моей работе тратить дни на то, чтобы заставить продукт проявить заявленные возможности считается непозволительной роскошью). Вообще говоря, можно ограничиться набором DLL-библиотек из Pervasive.SQL 2000 Workgroup Engine, которые достаточно переписать в директорию с приложением, или в директорию, прописанную в путях, чтобы можно было работать с Btrievом. Ну - удачи!

Необходимое окружение. Прежде всего в директорию, содержащую исходники Delphi-приложения, нужно поместить вышеупомянутые DLL и файлы Btrapi32.pas и BtrConst.pas из Pervasive SDK 2000 и в uses прописать BtrConst и BtrApi32. Если кому интересно назначение этих файлов, может посмотреть сам - там все достаточно прозрачно. Затем в type нужно прописать следующие два типа:

CLIENT_ID = packed record

  networkandnode : array[1..12] of char;

  applicationID : array[1..3] of char;

  threadID : smallint;

end;

VERSION_STRUCT = packed record

  version : smallint;

  revision : smallint;

  MKDEId : char;

end;

а в var следующие переменные:

client : CLIENT_ID; {вручную не переинициализировать!}

versionBuffer : array[1..3] of VERSION_STRUCT; {вручную не переинициализировать!}

status : smallint; {вручную не переинициализировать!}

posBlock : string[128]; {вручную не переинициализировать!}

dataBuffer : array[0..255] of char;

keyBuf : string[255];

keyNum : smallint;

dataLen : word;

Физический смысл большинства из этих переменных мне ясен смутно, но он и не важен. Будем считать их частью черного ящика. Переменные, помеченные комментарием {ВРУЧНУЮ НЕ ПЕРЕИНИЦИАЛИЗИРОВАТЬ!} являются системными, Btrieve сам их как-то заполняет и потом с ними работает. Остальные же несут разную смысловую нагрузку в зависимости от действия.

Подключение к Btrieve-БД (SQL: Database & Connect в одном флаконе). Чтобы производить любые операции с данными Btrieve, нужно в первую очередь подконнектиться к базе. Чтобы подключиться, нужно выполнить следующий фрагмент кода:

fillchar(keyBuf, sizeof(keyBuf), #0);

keybuf := '<Полный путь к любому из *.btr файлов в директории, где лежит БД>' + #0;

fillchar(client.networkAndNode, sizeof(client.networkAndNode), #0);

client.applicationID := 'MT' + #0; {так надо}

сlient.threadID := 50; {так надо}

fillchar(versionBuffer, sizeof(versionBuffer), #0);

dataLen := sizeof(versionBuffer);

status := BTRVID(B_VERSION, {системная константа}

  posBlock, {системная}

  versionBuffer, {системная}

  dataLen, {см.выше}

  keyBuf[1], {см.выше}

  0,

  client); {системная}

if status = B_NO_ERROR значит подконнектилось успешно, иначе - по каким-то причинам не получилось. Причины (из известных) могут быть следующие - приложение не нашло необходимые DLL-ки, неправильно указан путь в keybuf, кривой btr-файл. Подробно ошибки описаны в Pervasive SDK 2000 хэлпах, или в {списке ошибок СУБД Btrieve}.

Отключение от Btrieve-БД (SQL: Disconnect & Close database).

dataLenHead := 0;

status := BTRVID( B_STOP, {системная константа}

  posBlock, {системная}

  DataBuffer, {см.выше}

  dataLen, {см.выше}

  keyBuf[1], {см.выше - предыдущий раздел}

  0, {}

  client ); {системная}

Желательно в конце работы это делать. Во избежание.

Открытие таблицы(SQL: Аналог отсутствует). Для выполнения любой операции с таблицей (select/insert/update/delete) необходимо сначала ее открыть. Следующий фрагмент открывает одну отдельно взятую таблицу:

fillchar(keyBuf, sizeof(keyBuf), #0);

keybuf := '<Полный путь к *.btr файлу, где лежит таблица>' + #0;

fillchar(dataBuffer, sizeof(dataBuffer), #0);

dataLen := 0;

status := BTRVID(B_OPEN, {системная константа}

  PosBlock, {системная}

  dataBuffer, {см.выше}

  dataLen, {см.выше}

  keyBuf[1], {см.выше}

  0,

  client) {системная}

Если status != B_NO_ERROR, значит, что-то не сложилось. Или файл кривой, или путь неправильный, или с ним уже кто-то работает, или таблица уже открыта, или см. ошибки. Вообще говоря, можно открывать сразу несколько таблиц, и одновременно с ними работать. Но в этом случае для корректной работы нужно для каждой таблицы завести свой набор переменных

posBlock,

dataBuffer,

keyBuf,

keyNum,

dataLen

Наверное, можно даже применить массивы.

Закрытие таблицы(SQL: Аналог отсутствует). Все то же самое, как в открытии таблицы. Единственное отличие - B_CLOSE вместо B_OPEN. Для вящей корректности после окончания работ с таблицей нужно ее закрыть.

Добавление записи(SQL: INSERT). Для работы с конкретной таблицей необходимо:

1) Чтобы на эту таблицу было наложено заклинание эксклюзивного доступа... (Sorry, пиво...) Продолжаю на трезвую голову. Так вот: для работы с таблицей на самом деле необходимо следующее-

1) Должна быть описана структура таблицы. Например (таблица хозяйственных операций "Паруса"):

type

OPERHEAD_STRUCT = packed record

ISN : integer;

opDate : array[0..8] of char;

agnFrom : array[0..15] of char;

agnTo : array[0..15] of char;

docType : array[0..5] of char;

docNumb : array[0..12] of char;

docDate : array[0..8] of char;

basType : array[0..5] of char;

basNumb : array[0..12] of char;

basDate : array[0..8] of char; {см. ссылку в тексте}

resSum : double;

spMark : array[0..5] of char;

opCont : array[0..80] of char;

invSign : smallint;

subAgn : array[0..15] of char;

appName : array[0..8] of char;

appIsn : longint;

resMSum : double; {см. ссылку в тексте}

sysNumb : array[0..3] of char;

regNumb : longint;

opMngCnt : array[0..80] of char;

end;

var

OperheadRecord : OPERHEAD_STRUCT;

Важно! Для корректной работы должен быть соблюден размер полей в байтах. Через Database Explorer можно посмотреть структуру Btrieve-таблицы, с которой нужно работать. Там мы увидим, что поле resMSum, например, типа FLOAT и размером 8 байт. Этим размером и свойствами в Delphi обладает тип double. Поля типа CHAR в Btrieve имеют две характеристики - логическую длину и физическую (на байт больше). Это также видно в DBE. Поле basDate, например, логически длиной 9 байт, а физически - 10. Нужно исходить из логической длины, и поля типа CHAR описывать как начинающиеся с нуля массивы of char. Поле basDate в этом случае представляется как массив 0..8, т.е. 9 байт.

2) Данная запись должна быть проинициализирована. Вообще Btrieve все аналоги SQL-операций может выполнять только с записью целиком. Поэтому перед каждым "INSERT"ом или "UPDATE"ом нужно, чтобы все поля записи были заполнены нужным образом. Специфика заполнения такова:

а) Текстовые поля:

StrPCopy(OperheadRecord.agnto, AsString со значением + #0);

  { собственно присвоение значения }

CharToOem(OperheadRecord.agnto,OperheadRecord.agnto);

  { конвертация - если необходимо. CharToOem всего лишь одна из набора }

  { конвертационных функций из MustDie SDK }

б) Числовые поля:

OperheadRecord.resmsum := AsFloat со значением;

Здесь главное - совместимость типов. Достаточно легко определяется.

в) Автоинкременты:

fillchar(OperheadRecord.isn , SizeOf(OperheadRecord.isn), #0);

Независимо от типа. Просто заполняем их нулевыми байтами, Btrieve сам присвоит нужное значене.

3) Собственно INSERT :

dataLen := sizeof(OPERHEAD_STRUCT);

status := BTRVID(B_INSERT, {системная константа}

  PosBlock, {системная}

  OperheadRecord, {собственно запись - см.выше}

  dataLen, {см.выше}

  keyBuf, {путь к таблице - см.выше}

  -1,

  client) ; {системная}

Статус, понятно, должен оказаться равен B_NO_ERROR.

Позиционирование/Поиск(SQL: SELECT & FETCH в одном флаконе). Я для работы обошелся всего тремя опциями - B_GET_EQUAL, B_GET_FIRST, B_GET_NEXT. Вообще их там больше. Но поскольку даже в совокупности они все равно не заменят всю прелесть SQL, лучше потратить силы не на изучение всяких нюансов сомнительной ценности, а на то, чтобы избежать использования Btrieve в принципе :-). Для начала - общая информация. B_GET_EQUAL предназначен для выборки одной записи из таблицы. Если результатом запроса будет выборка из более чем одной записи, он вернет первую и на этом успокоится. B_GET_FIRST инициализирует выборку из более чем одной записи, и возвращает первую из выборки (скажу сразу - сортировка мне была не нужна, насчет нее ничего не знаю.). Если дальше мы будем выполнять B_GET_NEXT, то за каждое выполнение будем получать по одной следующей записи из выборки. Причем если упрется в конец файла, то выдаст status с кодом 9. В противном случае похоже, что просто пойдет дальше по файлу, несмотря на то, что начиная с какой-то записи все последующие уже не будут отвечать условиям выборки. Скажу сразу, что здесь я не уверен до конца в своих знаниях, могу ошибаться. Короче, у меня в программе в WHILE с GET_NEXTами стоит проверка сразу двух условий - чтобы status был B_NO_ERROR и чтобы полученные значения условиям выборки отвечали. Хотя бы одно не выполнилось - из WHILE выхожу. Пока работает. И последнее. Все эти GETы могут искать только по полям, описанным в индексах таблицы. Свое мнение об этом деликатно опускаю. Теперь - собственно описание синтаксиса. Для того, чтобы выполнить B_GET_EQUAL, нужно:

а) Описать структуру индексов. Например, в уже упомянутой таблице OPERHEAD есть следующие индексы:

type

OPERHEAD_INDEX7 = packed record

  appIsn : longint;

  appName : array[0..8] of char;

end;

OPERHEAD_INDEX0 = packed record

  ISN : integer;

end;

var

OperHeadIndex0 : OPERHEAD_INDEX0; {индекс номер 0}

OperHeadIndex7 : OPERHEAD_INDEX7; {индекс номер 7}

Информацию об индексаx можно посмотреть в том же DBE.

б) Далее - код:

OperheadIndex0.isn := значение AsInteger; {присвоение параметров поиска}

fillchar(OperheadRecord , SizeOf(OperheadRecord), #0);

dataLen := sizeof(OPERHEAD_STRUCT);

status := BTRVID(B_GET_EQUAL, {системная константа}

  PosBlock, {системная}

  OperheadRecord, {сюда будет возвращен результат поиска}

  dataLen, {см.выше}

  OperheadIndex0, {см.выше}

  0, {номер индеска - см.выше}

  client); {системная}

Если status <> B_NO_ERROR and <> B_KEY_VALUE_NOT_FOUND - значит, чего-то нашлось.

Использование других GETов осуществляется по этой же схеме. Единственная разница - вместо B_GET_EQUAL нужно поставить B_GET_FIRST или B_GET_NEXT. Важно! B_GET_EQUAL может использовать только уникальные индексы! B_GET_FIRST и B_GET_NEXT - любые.

Обновление записи(SQL: UPDATE). Самое главное - здесь рассмотрен вариант обновления одной записи. У меня сложилось впечатление, что вообще в Btrieve можно обновлять и удалять только по одной записи, но поскольку у меня не хватило терпения изучить HELP до конца, наверняка утверждать не могу. Итак: Непосредственно перед действием обновления у нас должен быть выполнен B_GET_EQUAL, который спозиционирует указатель в таблице именно на ту запись, которую мы будем апдейтить. ( У меня есть подозрение, что информация о позиционировании хранится в PosBlockе. Впрочем, какая разница?) Далее мы должны полностью заполнить запись таблицы (в нашем случае - OperheadRecord). Вообще говоря, поскольку только что выполнился B_GET_EQUAL, OperheadRecord у нас уже заполнен. Мы можем просто переприсвоить те поля, какие хотим изменить. Специфику заполнения см. в разделе, посвященном INSERTу. Далее - код:

dataLen := SizeOf(OPERHEAD_STRUCT);

status := BTRVID(B_UPDATE, {системная константа}

  posBlock, {системная}

  OperheadRecord, {см.выше}

  dataLen, {см.выше}

  keyBuf, {путь к таблице - см.выше}

  -1,

  client) {системная}

Status, сами понимаете, должен оказаться B_NO_ERROR. Если все в порядке.

Удаление записи(SQL: DELETE). Использование практически совпадает с B_UPDATE. В смысле, сначала должен быть B_GET_EQUAL и все такое. Фрагмент кода немного отличается - B_DELETE вместо B_UPDATE, и DataBuffer вместо OperheadRecord - какой смысл передавать данные, если запись сейчас будет удалена?

fillchar(dataBuffer, sizeof(dataBuffer), #0);

dataLen := SizeOf(OPERHEAD_STRUCT);

Status := BTRVID(B_DELETE, {системная константа}

  PosBlock, {системная}

  DataBuffer, {см.выше}

  dataLen, {см.выше}

  KeyBuf, {путь к таблице - см.выше}

  -1,

  client) {системная}

Про status уже и не говорю.

Заключение. Вот, собственно и все, что мне известно. В принципе, в разрозненном виде это все есть и в Pervasive SDK 2000 Help, и в Инете, но мне, например, понадобилось две недели, чтобы вычленить именно эту информацию, абстрагироваться от ненужной, и c прискорбием убедиться в несостоятельности обычного Pervasive ODBC. Может, данный документ кому-то сэкономит время. Хотя лучше всего, если эта информация вам не понадобится вовсе!

{vic@regentgroup.ru}