Модуль DbfCtrl

Модуль DbfCtrl download предназначен для доступа к базам данных построенных по DLB (Direct Link Base) технологии. Для хранения информации в таких базах используются DBF-файлы. Поэтому этот модуль может быть также использован для доступа к отдельным таблицам формата dBase III. В отличии от dBase III здесь слегка модифицирован заголовок файла. Он имеет вид:

typedef struct tagdbHEAD{
  BYTE		 Version;
  BaseDate	 CreateDate;
  DWORD		 RecCount;	
  WORD		 Location;	
  WORD		 RecordLen; 
  DWORD		 DelRecNumber;	
  DWORD		 DelRecCount;	
  char		 reserv[12];	
} dbHEAD;

/* 32 байта, заголовок dbf */
/* Версия базы 03 */
/* Дата последней модификации */
/* Количество записей */
/* Размер заголовка, включая CR */
/* Размер кортежа */
/* Первая удаленная запись */
/* Количество удаленных записей */

Особенность баз данного типа состоит в следуещем.
Первое, отсутствии индексных файлов. При этом для формирования взаимных ссылок между таблицами базы используется непосредственное указание номера записи связанной таблицы. Например:

Т.о. товар 133ЛА3 и 133ИД1 имеет в качестве производителя ИНТЕГРАЛ, а товар 140УД12 - КВАЗАР.

Второе, если в таблице присутствует поле с именем LINK, то это поле используется для организации списка удаленных записей. Например:

Т.о. имеем цепочку удаленных записей 3,2,6. При добавлении новой записи она будет записана в позицию первой записи в цепочке. Т.е. таблица примет вид:

Третье, база поддерживает организацию цепочек записей для связи таблиц типа заголовок, содержание.Например:

При этом для доступа к таблице содержание используется функция Chain.

Четвертое, база поддерживает блокировку на уровни таблиц с помощью функции Lock, что обеспечивает целостность базы.

Пятое, поддерживается авторизованный доступ (см.Right). Для этого таблица должна иметь поле PROT, типа 8C0. В это поле автоматически записывает информация заданная функцией User.

Все функции и методы модуля можно разбить на группы:

Функции доступа к базе:
Open- открывает существующую таблицу базы данных.
Create- создает новую таблицу базы данных.
Close- закрывает таблицу.
Link- связывание полей таблиц базы.
Chain- строит цепочку записей таблицы.
Flush- вкл/выкл сброс буферов.
Lock- блокирует/разблокирует базу.
Struct- возвращает описатель структуры базы.
User- устанавливает идентификатор пользователя.
Right- устанавливает права доступа пользователя.

Методы упорядочения записей:
Filter- устанавливает фильтр.
Sort- устанавливает поле для сортировки.
Action- выполняет отбор и сортировку записей.

Методы доступа к записям:
Deleted- проверяет удалена-ли запись.
RecGet- читает запись.
Edit- взять на редактирование, подготовить новую запись.
Update- сохранить запись.
Remove- удалить запись.
Find- ещет запись по фрагменту.

Методы доступа к полям:
Field- возвращает номер поля по имени.
FldGet- возвращает содержание поля.
FldGetStr- возвращает содержание поля как строку.
FldPut- устанавливает содержание поля.
FldPutStr- устанавливает содержание поля как строку.
FldCmp- сравнивает содержание поля с переменной.

Список функций и методов

Create

Назначение.Создает новую таблицу базы данных.

Create( LONG<hWnd>, STRING<sBaseName> ) LONG<pClass>

hWnd - описатель родительского окна.
sBaseName - описатель структуры базы.

Описание.В случае успешного выполнения функция возвращает объект открытой таблицы, Описатель структуры таблицы имеет вид:

FILENAME:FIELDNAME,DECLARE|...

FILENAME - полное имя файла или псевдоним. Если указан псевдоним то истинное имя файла должно быть указано в файле DbfCtrl.ini в секции [Alias].
FIELDNAME - имя поля, не более 10 символов.
DECLARE - описатель поля вида <Размер поля><Тип поля><Дробная часть>, а именно:

Идентификатор	Тип	Длинна	Пример
C	char	1..255	20C0
N	numeric	1..20	10N0
F	float	1..20	10N2
D	date	8	8D0
L	logical	1	1L0
M	memory	0..64000	10M0

В случае неудачи функция отображает окно с сообщением об ошибке, после чего если определен hWnd посылает окну сообщение WM_POWER с wParam содержащим код ошибки и возвращает нулевой идентификатор базы.

Пример:

SET Dbf=DBFCTRL!Create(HWND,"REPORT:WARE,20C0|SUMMA,16N2")
IF EMPTY(Dbf) GOTO CLOSE
...
ERASE Dbf.Close

Open

Назначение.Открывает существующую таблицу базы данных.

Open( LONG<hWnd>, STRING<sBaseName> ) LONG<pClass>

hWnd - описатель родительского окна.
sBaseName - описатель структуры базы.

Описание.В случае успешного выполнения функция возвращает объект таблицы базы. Описатель структуры таблицы имеет один из следующих видов:

1. FILENAME. Т.е. просто полное имя файла или псевдоним. Если указан псевдоним то истинное имя файла должно быть указано в файле DbfCtrl.ini в секции [Alias].
2. FILENAME:FIELD1|FIELD2... последовательность имен полей таблицы. В этом случае все остальные поля таблицы становятся недоступными.
3. FILENAME:FIELD1|FIELD2(FILENAME2:NAME|...)|... в этом случае поле FIELD2 связывается с первым полем NAME таблицы заданной FILENAME2.
4. FILENAME:FIELD1|FIELD2[KEY,WORD|...] в этом случае поле FIELD2 раскрывается по словарю. Сам словарь состоит из последовательности набора KEY - ключевая комбинация символов сохраняемая в поле таблицы и WORD - текстовое выражение возвращаемое при запросе к полю.

В случае неудачи функция отображает окно с сообщением об ошибке, после чего если определен hWnd посылает окну сообщение WM_POWER с wParam содержащим код ошибки и возвращает нулевой идентификатор таблицы базы.

Пример:

SET Dbf=DBFCTRL!Open(HWND,"REPORT:WARE,20C0|SUMMA,16N2")
IF EMPTY(Dbf) GOTO CLOSE
...
ERASE Dbf.Close

Close

Назначение.Закрывает таблицу.

Close

Пример:

ERASE Dbf.Close

Link

Назначение.Связывание полей таблиц баз.

Link( STRING<sField>, STRING<sStruct> ) LONG<pClass>

sField - имя к которому привязывается таблица словаря.
sStruct - описатель связанной таблицы.

В случае неудачи функция отображает окно с сообщением об ошибке, после чего если определен hWnd посылает окну сообщение WM_POWER с wParam содержащим код ошибки и возвращает нулевой идентификатор базы. Все связанные таблицы автоматически закрываются при закрытии основной таблицы базы.

Пример:

SET Dbf=DBFCTRL!Open(HWND,"REPORT:WARE|SUMMA|PROIZW")
IF EMPTY(Dbf) GOTO CLOSE
SET Lnk=Dbf.Link("PROIZW","PROIZW:NAME|PNAME")
IF EMPTY(Lnk) GOTO CLOSE
...
CLOSE
ERASE Dbf.Close

Chain

Назначение.Строит цепочку записей для связанной таблицы базы.

Chain( OBJECT<Own>, LONG<Rec> ) LONG<Count>

Own - идентификатор таблицы от которой строится цепочка.
Rec - номер записи в таблице от которой строится цепочка.
Count - количество записей в цепочки.

Описание.Метод связывает две открытые таблицы. Текущая таблица рассматривается как содержание, а Own - как таблица заголовка. Связь имеет вид:

Таблица TITLE NUMBER OWN ... ... 1010101 10 ... ...

Таблица CONTENS   WARE LINK ... ... ... 10 133ЛА3 14 ... ... ... 14 1401УД12 0 ... ... ...

Т.о. поле OWN таблицы TITLE содержит номер первой записи цепочки, а поле LINK таблицы CONTENS образует связанный список записей содержания. Причем добавление или удаление записи из таблицы содержания приводит к автоматической модификации записи заголовка. Эта операция выполняется как транзакция, что гарантирует целостность базы.

Пример:

SET Dbf=DBFCTRL!Open(HWND,"CONTENS:WARE|SUMMA")
IF EMPTY(Dbf) GOTO CLOSE
SET Own=DBFCTRL!Open(HWND,"TITLE:NUMBER|OWN")
IF EMPTY(Own) GOTO CLOSE
RecOwn=Own.RecGet(1)
RecLnk=Own.FldGet("OWN")
RecCnt=Dbf.Chain(Own,RecLnk)
 FOR Rec=1 TO RecCnt
  Dbf.RecGet(Rec)
  ...
 NEXT
CLOSE
ERASE Own.Close
ERASE Dbf.Close

Flush

Назначение.Вкл/выкл сброс буферов.

Flush( BOOL<On> )

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

Lock

Назначение.Блокирует/разблокирует таблицу базы.

Lock( BOOL<On> )

Описание.Метод блокирует/разблокирует таблицу базы. Фактически блокируется заголовок таблицы, что приводит к невозможности его модификации другим процессом, а следовательно и любой записи таблицы. Эта операция используется когда в модификации учавствуют несколько связанных таблиц.

Struct

Назначение.Возвращает описатель структуры базы.

Struct() VARIABLE

Описание.Метод возвращает описатель структуры таблицы в формате аналогичном функции Create.

User

Назначение.Устанавливает идентификатор пользователя..

User( STRING<sUser> )

sUser - идентификатор пользователя в виде:<UserGruppa><UserNumber>.

Описание.Метод устанавливает группу и код пользователя. Код должен соответствовать номеру записи в таблице PasUser.Dbf (не более 6 цифр). После выполненя данного метода и наличии поля PROT в него автоматически записывается:
Первый сивол код доступа (по умолчанию G)

Символ	Назначение
P	Доступ разрешен только пользователю создавшему данную запись
G	Доступ разрешен членам группы, которой принадлежит пользователь.
A	Доступ разрешен всем пользователям.

Второй символ код группы пользователя, создавшего эту запись.
Далее идет код пользователя.

Right

Назначение.Устанавливает права доступа пользователя..

Right( STRING<sRight> )

sRight - список групп к которым разрешен доступ пользователя.

Описание.Метод устанавливает массив групп к которым разрешен доступ пользователя. Если для данной таблицы выполнен этот метод и таблица имеет поле с именем PROT, то при выполнение операции Action отбираются только записи доступ к которым данному пользователю разрешен. Если вместо строки передается 0 или код администратора "@", то даже при наличии поля PROT будут доступны все записи. Решение о доступе принимается следующим образом:

  IF ProtField THEN
   IF UserRight[0] != PROT_ADMIN THEN
	char buf[6];
	GetFld_C( ProtField, buf, sizeof(buf) );
	IF	  buf[0]==PROT_PRIVATE THEN
	  if( strcmp( &(buf[2]), UserNumber )!=0 ) return TRUE;

	ELSIF buf[0]==PROT_GRUPPA  THEN
	  if( strchr( UserRight, buf[1] )==NULL ) return TRUE;

	ENDI
   ENDI
  ENDI
  return FALSE;

Filter

Назначение.Устанавливает фильтр.

Filter( STRING<sFilter> ) BOOL

sFilter - описатель фильтра.

Описание.Описатель фильтра имеет вид

(FIELD_NAME[:LINK_NAME]<код условия><шаблон>[&,|])[&,|]...

---

FIELD_NAME	имя поля.
LINK_NAME	имя поля связанной таблицы.
Условие	Код условия Условие = равно # не равно > больше или равно < меньше или равно $ подобно
Значение
Альтернатива	& - AND, | - OR

---

Т.о. в случае связанного поля можно налагать условие на любое доступное поле связанной таблицы.

Пример.

ok=Dbf.Filter("(COD>1&<3)&(PROIZW=ИНТЕГРАЛ|=КВАЗАР)")

Sort

Назначение.Устанавливает поле для сортировки.

Sort( STRING<sField> ) BOOL

sField - имя поля.

Описание.Метод устанавливает сортировку по возрастанию для указанного поля. Если в качестве имени указывается 0, то сортировка снимается.

Пример.

ok=Dbf.Sort("NAME")

Action

Назначение.Выполнить отбор и сортировку записей.

Action( LONG<hDlg> ) LONG<Count>

hDlg - описатель окна указателя PBOPEN.

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

Пример.

ok=Dbf.Filter("(COD>1&<3)&(PROIZW=ИНТЕГРАЛ|=КВАЗАР)")
ok=Dbf.Sort("PROIZW")
hPB=DBFCTRL!PBOPEN($HWND,"Сортировка")
RecCnt=Dbf.Action(hPB)
DBFCTRL!PBCLOSE(hPB)

Deleted

Назначение.Проверяет удалена-ли запись.

Deleted() BOOL

Описание.Если запись удалена, то возвращается истина, иначе ложь.

RecGet

Назначение.Читает запись.

RecGet( LONG<Rec> ) LONG

Rec - номер записи.

Описание.Метод возвращает указанную запись.

Пример.

ok=Dbf.Filter("(COD>1&<3)&(PROIZW=ИНТЕГРАЛ|=КВАЗАР)")
ok=Dbf.Sort("PROIZW")
hPB=DBFCTRL!PBOPEN($HWND,"Сортировка")
RecCnt=Dbf.Action(hPB)
DBFCTRL!PBCLOSE(hPB)
FOR rec=1 TO RecCnt
 Dbf.RecGet(rec)
 ...
NEXT
ERASE Dbf.Close 

Edit

Назначение.Взять на редактирование, подготовить новую запись.

Edit( LONG<Rec> ) LONG

Rec - номер записи.

Описание.Метод берет на редактирование указанную запись. В случае нулевой записи метод подготавливает буфер для приема новой записи. Метод возвращает номер фактически прочитанной записи, т.к. если номер больше кол-ва записей, то возвращается последняя запись.

Пример.

Dbf.Edit(Rec)
Dbf.FldPut("PROIZW",10)
ok=Dbf.Update(Rec)

Update

Назначение.Сохранить запись.

Update( LONG<Rec> ) LONG

Rec - номер записи.

Описание.Метод сохраняет отредактированную запись. В случае нулевой записи метод добавляет новую записи. Метод возвращает номер новой записи.В случае ошибки возвращается ноль.

Пример.

Dbf.Edit(Rec)
Dbf.FldPut("NAME","133ЛА3")
ok=Dbf.Update(Rec)

Remove

Назначение.Уничтожает запись.

Remove( LONG<Rec> ) BOOL

Rec - номер записи.

Описание.Метод удаляет указанную запись. В случае наличия LINK поля, запись включается в цепочку удаленных, иначе помечается для удаления

Пример.

Dbf.Remove(Rec)

Find

Назначение.Возвращает номер первой записи удовлетворяющей шаблону.

Find( STRING<sField>, STRING<sPattern> ) LONG

sField - имя поля. sPattern - фрагмент строки.

Описание.Метод возвращает номер первой записи удовлетворяющей шаблону. Если поиск идет по полю, по которому установлена сортировка, то используется метод быстрого поиска.

Пример.

Rec=Dbf.Find("NAME","133")

Field

Назначение.Возвращает номер поля.

Field( STRING<sField> ) LONG

sField - имя поля.

Пример.

hf=Dbf.Field("NAME")

FldGet

Назначение.Возвращает содержание поля.

FldGet( STRING<sField> ) VARIABLE

sField - имя поля.

Описание.Метод возвращает содержание поля.

Тип поля	DBasic тип
char	STRING
numeric	LONG
float	REAL
date	LONG
logical	BOOL
memory	STRING

Пример.

V=Dbf.FldGet("NAME")

FldGetStr

Назначение.Возвращает содержание поля как строку.

FldGetStr( STRING<sField> ) VARIABLE

sField - имя поля.

Описание.Метод возвращает содержание поля всегда как строку.

Пример.

V=Dbf.FldStr("NAME")

FldPut

Назначение.Устанавливает содержание поля.

FldPut( STRING<sField>, VARIABLE<V> ) BOOL

sField - имя поля.
V - переменная.

Описание.Метод устанавливает содержание поля.

Пример.

ok=Dbf.FldPut("NAME","133ЛА3")

FldPutStr

Назначение.Устанавливает содержание поля.

FldPutStr( STRING<sField>, STRING<V> ) BOOL

sField - имя поля.
V - переменная.

Описание.Метод устанавливает содержание поля принимая в качестве данных строку.

Пример.

ok=Dbf.FldPutStr("NAME","133ЛА3")

FldCmp

Назначение.Сравнивает содержание поля с переменной.

FldCmp( STRING<sField>, VARIABLE<V> ) LONG

sField - имя поля.
V - переменная.

Описание.Метод сравнивает переменную со значением поля и возвращает 0- при их равенстве, -1- если значения поля меньше и 1- если больше.

Пример.

RecCnt=Dbf.Action(0)
FOR rec=1 TO RecCnt
 Dbf.RecGet(rec)
 r=Dbf.FldCmp("NAME","133ЛА3")
 IF r=0 THEN EXIT
NEXT