Интернет системы

IBSQL

TIBSQL = class(TComponent)

 

Компонент, являющийся минимальной  надстройкой над InterBase API. В отличие  от IBTable, IBQuery и IBDataSet он не буферизирует выбираемые записи - для доступа  к текущей записи существует только свойство Current (IBSQL не является наследником DataSet). Работа с параметрами и столбцами  несколько отличается от обычной, т.к. они являются TIBXSQLVAR, то есть прямыми ссылками на структуры InterBase API.

 

У IBSQL есть свойство GoToFirstRecordOnExecute - если True (по умолчанию), то в случае select компонент запросит у сервера  первую запись и заполнит ее данными Current. Если False - Current будет пустым, и  для считывания данных с сервера  необходимо выполнить IBSQL.Next.

 

Предназначен для выполнения операторов Insert/update/delete, execute procedure, или select для небуферизированного перебора записей (например при импорте/экспорте данных или при массовой обработке записей на клиенте).

IBStoredProc

TIBStoredProc = class(TIBCustomDataSet)

 

Компонент для выполнения хранимых процедур. Собственно, выполнять  процедуры можно вызывая EXECUTE PROCEDURE в компонентах IBQuery и IBSQL. Унаследован от IBCustomDataSet, но как таковым DataSet-ом не является. Поэтому для выборки из селективных процедур (select * from proc) следует использовать обычные IBDataSet, IBQuery, IBSQL (IBStoredProc принципиально не умеет работать как DataSet по простой причине - выполнение процедур в нем предусмотрено только как execute procedure). В общем случае не рекомендуется к использованию, т.к. имеет застарелую проблему с обработкой ошибок. При самостоятельном исправлении данной ошибки в коде (IBStoredProc.pas) может быть использован, однако при установке обновлений IBX нужно проверить новую версию IBStoredProc на исправления (что маловероятно).

 

Примеры вызова обычных и  селективных процедур через IBDataSet, IBQuery и IBSQL даны в статье.

 

! помните, что указанная  выше проблема с обработкой  ошибок относится к вызовам  execute procedure во всех компонентах  IBX - IBStoredProc, IBQuery, IBDataSet, IBSQL, ...

EIBError

 

Базовый класс ошибок IBX. Имеет  свойства (кроме унаследованных от EDatabaseError):

SQLCode - номер ошибки (статус  вектора) при выполнении операторов SQL

IBErrorCode - целое число, идентифицирующее  ошибку. Описание всех ошибок  сервера находится в LangRef.pdf (а  также перечислено в IBErrorCodes.pas)

 

В свою очередь, на основе EIBError в IBX существует несколько дополнительных классов

EIBInterBaseError - общая ошибка  сервера 

EIBInterBaseRoleError - ошибки при  использовании ROLE

EIBClientError - ошибки, специфичные  для клиентской части (gds32.dll, fbclient.dll). В основном для указания на  несовместимости конкретной клиентской  части. 

EIBPlanError - ошибка получения  плана запроса

 

К сожалению, затея с разделением EIBError на классы хоть и хорошая, но в  коде реализована плохо. Например, EIBPlanError и EIBInterBaseRoleError вызываются в коде только по одному разу. Поэтому необходимо проверять EIBError, а наследованные  от него классы можно игнорировать, или использовать только EIBInterBaseError и EIBClientError в дополнение к EIBError.

 

Примеры обработки ошибок при работе с транзакциями приведены  дальше.

IBDatabaseInfo

 

Компонент для получения  информации о параметрах БД и статистике выполнения запросов. Подсоединяется к IBDatabase, информацию возвращает только посредством runtime-свойств. Наиболее часто  используемые свойства

UserNames - список пользователей,  подключенных к серверу архитектуры  SuperServer. Для Classic возвращает только  текущего пользователя.

Reads, Writes, Fetches - информация  о числе чтений, записи и обращений  к страницам БД. Аналог информации, выводимой IBExpert и др. инструментами  после выполнения запроса.

PageSize, ODSxxx, NumBuffers, SweepInterval ... - информация о свойствах БД

ReadSeqCount, UpdateCount, InsertCount ... - счетчики  соответствующих операций, выводятся  для всех таблиц (поштучно). В предыдущих  версиях IBX представляли собой  integer, что неверно (выводился мусор  вместо правильной информации). Аналог  информации, выводимой в закладке Performance Info IBExpert.

IBSQLMonitor

 

Компонент для мониторинга  действий клиентского приложения (вызовов IB API). Для мониторинга необходимо в событии OnSQL сохранять EventText и EventTime либо в файле, либо в компоненте TMemo на какой-либо форме (например Memo.Lines.Add(EventText)). Возможен мониторинг (свойство TraceFlags):

tfQPrepare - вызов Prepare запроса 

tfQExecute - вызов Execute запроса.  Выдается текст запроса, хотя  на самом деле в этот момент  он на сервер не передается (был уже передан при Prepare)

tfQFetch - выборка 1-й записи  с сервера

tfError - ошибки, возникающие  на сервере

tfStmt - операции с запросами  (аллокирование, закрытие, и т.п.)

tfConnect - подключение к базе  данных или отключение 

tfTransact - операции с транзакциями - Start, Commit, Rollback, CommitRetaining, Rollbackretaining

tfBlob - операции с blob (чтение, запись)

tfService - вызовы Services API

tfMisc - остальное

 

Для активации монитора нужно  у соответствующего компонента IBDatabase также выставить опцию TraceFlags.

 

В некоторых (старых) версиях IBX были проблемы с мониторингом (зависало приложение), если компонент IBSQLMonitor использовался  в приложениях, работающих как сервис.

 

Пример использования  есть в поставке, и называется SQLMonitor.

IBEvents

 

Компонент для регистрации  и приема событий, отправляемых сервером по оператору POST_EVENT. См. пример IBDemo в  поставке Delphi и C++Builder. Помните, что события  синхронные, то есть отправляются клиенту  только по commit транзакции, в которой  эти события произошли (до commit или  по rollback никакие события не отправляются).

IBExtract

 

Компонент для извлечения метаданных БД (таблиц, процедур, триггеров...) в виде скрипта.

 

Основные свойства:

IncludeSetTerm - включать команду  set term в скрипт, или нет. Необходимо (true) для последующего выполнения  скрипта в isql, IBExpert и др.

ShowSystem - выводить в скрипт ddl системных таблиц (rdb$...)

DatabaseInfo (runtime) - локальный экземпляр  IBDatabaseInfo

Items - результирующий скрипт с метаданными

Database - связь с компонентом  IBDatabase

Transaction - связь с компонентом  IBTransaction

 

Пример использования:

 

Извлечь полный скрипт

IBExtract1.ExtractObject(eoDatabase);

 IBExtract1.Items.SaveToFile('d:\a.ddl');

 

Извлечь только скрипт таблиц:

 IBExtract1.ExtractObject(eoTable);

 IBExtract1.Items.SaveToFile('d:\a.ddl');

 

Извлечь данные для таблицы Customer

 IBExtract1.ExtractObject(eoData, 'CUSTOMER');

 IBExtract1.Items.SaveToFile('d:\a.ddl');

 

Извлечь скрипт таблицы EMPLOYEE

 IBExtract1.ExtractObject(eoTable, 'EMPLOYEE');

 IBExtract1.Items.SaveToFile('d:\a.ddl');

 

Извлечь скрипт таблицы EMPLOYEE плюс все ее индексы, триггеры, домены, гранты, check и данные

IBExtract1.ExtractObject(eoTable, 'EMPLOYEE',

   [etDomain, etTable, etTrigger, etForeign, etIndex, etData, etGrant, etCheck]);

 IBExtract1.Items.SaveToFile('d:\a.ddl');

 

Извлечь скрипт процедуры SHIP_ORDER

 IBExtract1.ExtractObject(eoProcedure, 'SHIP_ORDER);

 IBExtract1.Items.SaveToFile('d:\a.ddl');

 

Извлечь скрипт (create и alter) процедуры SHIP_ORDER

 IBExtract1.ExtractObject(eoProcedure, 'SHIP_ORDER');

 IBExtract1.Items.SaveToFile('d:\a.ddl');

 

Извлечь скрипт alter procedure для SHIP_ORDER

 IBExtract1.ExtractObject(eoProcedure, 'SHIP_ORDER', etAlterProc);

 IBExtract1.Items.SaveToFile('d:\a.ddl'); 

IBConnectionBroker

 

Компонент для организации  пула коннектов. Пример использования - IBConnectionBroker. Для нормальной работы (параллельной работы с коннектами в threads) нельзя указывать локальный коннект (без имени сервера. Это допустимо только если используется Firebird Embedded версии 1.5). В случае работы приложения с IBConnectionBroker на сервере укажите строку коннекта у IBDatabase как localhost:c:\dir\data.gdb.

IBScript

 

Компонент для выполнения скриптов (набора команд в текстовом  файле).

 

Основные свойства:

AutoDDL - автоматически вызывать Commit после выполнения DDL-операторов

Dataset - компонент для выполнения sql-операторов скрипта. Рекомендуется  IBQuery.

Database - база данных, над  которой нужно выполнить скрипт (IBDatabase)

Transaction - транзакция, в которой  будет выполняться скрипт (IBTransaction)

Terminator - разделитель SQL-операторов  в скрипте 

Script - текст скрипта (TStrings, соответственно можно вызывать LoadFromFile и т.п.)

Statistics - статистика выполнения  скрипта (подробнее см. IBScript.pas)

Paused (runtime, read/write) - индикатор  состояния выполнения скрипта

Validating (runtime, readonly) - индикатор  выполнения проверки скрипта  (только prepare)

CurrentTokens (runtime) - набор токенов  выполняемого SQL-оператора

 

События:

OnExecuteError - при ошибке выполнения  конкретного оператора позволяет  вывести этот оператор, номер  строки в скрипте и ошибку, а также указать, прервать выполнение  скрипта или игнорировать ошибку  и выполнять скрипт дальше.

OnParse - при успешном выполнении  очередного оператора скрипта  позволяет узнать тип оператора  (TIBParseKind) и его текст.

OnParseError - при ошибке парсинга  оператора позволяет вывести  оператор, ошибку и номер строки  в скрипте. 

OnParamCheck - если у конкретного  оператора есть параметры, и  это не DDL, то позволяет задать  параметры оператора SQL перед  его выполнением (Params и ParamByName).

 

Методы:

ValidateScript - выполнять только prepare всех операторов скрипта,  чтобы убедиться, что они могут  быть выполнены (синтаксически  корректны).

ExecuteScript - выполнить скрипт

IBSQLParser

 

Компонент, которым пользуется IBScript для парсинга скрипта.

IBDatabaseINI

 

Компонент для записи и  считывания настроек IBDatabase в ini-файле. Пример использования:

 

Сохранение информации

procedure TForm1.Button1Click(Sender: TObject);

begin

  IBDatabaseINI1.ReadFromDatabase;

  IBDatabaseINI1.SaveToINI;

end;

 

Считывание информации

procedure TForm1.Button2Click(Sender: TObject);

begin

  IBDatabaseINI1.ReadFromIni;

  IBDatabaseINI1.WriteToDatabase(IBDatabase1);

end;

 

Информация хранится в  файле, указанном в свойстве FileName, в виде

 

[Database Settings]

database=localhost:D:\Firebird\examples\employee.fdb

user_name=SYSDBA

password=masterke

sql_role=

lc_ctype=win1251

Классы импорта/экспорта в IBSQL.PAS

 

Перенесены и чуть доработаны еще из FreeIBComponents.

 

Базовым классом является TIBBatch. От него унаследованы TIBBatchInput и TIBBatchOutput, которые также являются промежуточными. Конечные (готовые для использования) классы:

 

TIBOutputDelimitedFile, TIBInputDelimitedFile - импорт-экспорт  в файлы текстового формата,  каждая запись на отдельной  строке, столбцы нефиксированного  формата, возможность указать  разделитель.

 

Пример импорта:

procedure TForm1.Button1Click(Sender: TObject);

 

var

  Filename : String;

  InpFile : TIBInputDelimitedFile;

begin

  TW.StartTransaction;

  ImpFile:=TIBInputDelimitedFile.Create;

  ImpFile.Filename:='c:\data.csv';

  ImpFile.ColDelimiter:=','; // разделитель столбцов

  ImpFile.SkipTitles; // пропускаем заголовок с именами столбцов, если есть

  ImpSQL.Transaction:=TW; // связываем  компонент с транзакцией, если  это не сделано в дизайн-тайме

  ImpSQL.Clear; // это класс  IBSQL. Можно использовать и IBQuery

  ImpSQL.SQL.Add('insert into table (field1, field2, field3) ');

  ImpSQL.SQL.Add('values (:field1, :field2, :field3) ');

  ImpSQL.BatchInput(ImpFile);

  ImpFile.Free;

  TW.Commit;

end;

 

Для экспорта используется соответственно запрос select, TIBOutputDelimitedFile, и метод IBSQL.BatchOutput(). Несмотря на то, что у TIBQuery/TIBDataSet тоже есть метод BatchOutput, эти компоненты не рекомендуется использовать для экспорта. Дело в том, что IBQuery/IBDataSet - кэширующие DataSet-ы. То есть, по мере считывания и экспорта записей поштучно они будут накапливаться в буфере записей, и будет расти используемая клиентским приложением, и падать скорость экспорта. IBSQL наоборот, не имеет буфера (есть буфер только на 1 запись), и поэтому память при экспорте потребляться не будет, а скорость считывания записей будет зависеть только от производительности сервера и сети.

 

TIBOutputRawFile, TIBInputRawFile - импорт-экспорт  в файлы фиксированного формата,  без разделителей, аналог external table (собственно, можно экспортировать данные  в такой файл и использовать  его как external table). К этим компонентам  относится все то же самое, что было сказано выше в отношении TIBxxxDelimitedFile.

 

TIBOutputXML - класс для экспорта  в XML. Скорее, это не класс, а  record, или набор параметров для  экспорта в XML, поскольку никаких  методов или функций у TIBOutputXML (кроме наследуемых от TObject) нет.

 

Для экспорта в XML не требуется каких то специфических действий - достаточно создать экземпляр TIBOutputXML, заполнить его свойства, и вызвать TIBSQL.OutputXML();

Компоненты Services API (InterBase Admin)

 

 

 

Этот набор компонент  находится на отдельной закладке, и показывается в палитре компонент Delphi только в том случае, если на компьютере в path присутствует gds32.dll от InterBase 6.0 и выше или совместимая (для Firebird обязательно указание установки  совместимой gds32.dll в инсталляторе, или  ручная установка gds32.dll из fbclient.dll при  помощи утилиты instclient.exe). Компоненты используют Services API, введенный в InterBase 6.0 для backup/restore, проверки БД и других операций. Пример использования этих компонент есть в поставке и называется Admin (если вы не нашли этот пример в Demos/DB/IBX/, то можете скачать отсюда).

 

Services API как таковое должно  поддерживаться сервером, и поддерживается  во всех версиях SuperServer, начиная  с InterBase 6. Для Classic полноценно Services API поддерживается либо в Yaffil, либо в Firebird начиная с версии 1.5.2.

 

На картинке изображена форма  примера Admin в DesignTime.

 

У всех компонент Services API подключение  к серверу и БД производится двумя  свойствами - ServerName и DatabaseName. В отличие  от TIBDatabase в свойстве DatabaseName должен быть указан только локальный путь к БД (без имени сервера), а в ServerName - только имя сервера. Например:

IBS.DatabaseName:='c:\dir\data.gdb';

IBS.ServerName:='server';

Если в DatabaseName указать и имя сервера ('server:c:\dir\data.gdb'), компонент будет выдавать ошибку 'Error reading data from the connection'.

 

Все компоненты Services API предназначены  для выполнения сервером определенных команд. Сами компоненты (за исключением TIBInstall, TIBUninstall) никаких действий (кроме  передачи команд серверу и получения  результата) не производят.

 

У всех компонент (за исключением TIBInstall, TIBUninstall) имя пользователя и  пароль задаются в свойстве Params. Например:

 IBBackupService1.Params.Add('user_name=SYSDBA');

 IBBackupService1.Params.Add('password=masterkey');

 

TIBConfigService - позволяет получать  параметры сервера из файла  конфигурации ibconfig.

 

TIBBackupService - передает серверу  команду на выполнение резервного  копирования базы данных, аналог gbak -b с опцией -se. Файл бэкапа создается  сервером на том же компьютере, где находится сервер и база  данных. В случае необходимости  создать резервную копию на  другом компьютере, необходимо, чтобы  сервер стартовал не под LocalSystem, а под специально созданным  пользователем (т.к. LocalSystem не имеет  и не может получить никаких  прав на доступ к сетевым ресурсам),и этому пользователю были даны права на доступ к удаленному (сетевому) каталогу, куда требуется сохранять резервную копию.