Свойства

Conditions

Смотрите подробное описание в разделе "Выполнение SQL-запросов. Условия" о TpFIBDataSet Руководства пользователя.

Database
Это свойство возвращает базу данных, для которой будет работать транзакция.

GoToFirstRecordOnExecute
Свойство влияет на выполнение селективных SQL. Если оно установлено в True, то первый fetch будет сделан сразу же после выполнения. Если оно установлено в False, то первый fetch будет сделан только после вызова Next. Опция имеет смысл только для селективных запросов.

Options
Это свойство аналогично свойствам TpFIBDataSet и описывается следующим образом:

TpFIBQueryOption = (qoStartTransaction, qoAutoCommit, qoTrimCharFields, qoNoForceIsNull, qoFreeHandleAfterExecute); TpFIBQueryOptions=set of TpFIBQueryOption; 

NEW

qoStartTransaction – если включена, то перед выполнением запроса, если транзакция неактивна, то она будет стартовать автоматически.

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

qoTrimCharFields – определяет способ работы с CHAR-VARCHAR полями. Если опция включена, то методы Fields.asString, Fields.asWideString будут возвращать значения без хвостовых пробелов.

QoFreeHandleAfterExecute - указывает, что Handle запроса должен быть немедленно освобожден после выполнения в случае если запрос не селективный. Если запрос селективный, то Handle будет освобожден либо после выполнения метода Close, либо после того как все записи будут выбраны методом Next

qoNoForceIsNull- определяет надо ли преобразовывать текст SQL в случае использования параметров с NULL значениями. Например, допустим есть такой запрос:

Delete from table1 where Field1=:Field1

Если параметр Field1 принимает значение отличное от NULL, то этот запрос удалит все записи из таблицы, которые подпадают под условие запроса. Если же параметр принимает значение NULL, то запрос не удалит ни одной записи, так как для NULL значений условие всегда будет возвращать false. Для того, чтобы удалить записи в которых поле Field1 принимает значение NULL требуется переписать запрос как Delete from table1 where Field1 IS NULL.

То есть, разработчику необходимо отслеживать этот момент и менять текст запроса, в зависимости от значения параметра. FIBPlus упрощает эту работу, и изменяет текст запроса автоматически, в зависимости от текущего значения параметра. Если эта возможность разработчику не нужна, он может ее отключить вышеупомянутой опцией. Т.е. включение опции qoNoForceIsNull в Options компонента TpFIBQuery отключит данное преобразование.

ParamsCheck
Указывает производить ли парсинг текста запроса, для создания списка параметров, или нет. Если запрос не содержит параметров, то отключение этого свойства позволит сэкономить немного времени. Если же запрос является DDL запросом, то крайне желательно это свойство установить в false.

SQL
Это свойство возвращает текст выполняемого запроса

Transaction
Это свойство возвращает транзакцию, в контексте которой будет выполнен запрос.

Свойства

AfterExecute
procedure (Sender: Tobject); TnotifyEvent;
Это событие генерируется после выполнения SQL-запроса (вызова TpFIBQuery.ExecQuery, ExecProc, ExecWP).

BeforeExecute
procedure (Sender: Tobject);
Это событие генерируется перед выполнением.

OnBatchError
procedure (E: EFIBError; var BatchErrorAction: TbatchErrorAction); Это событие генерируется при ошибке выполнения пакетной обработки.

OnBatching
procedure (BatchOperation: TBatchOperation; RecNumber: Integer; var BatchAction: TbatchAction);
Это событие генерируется при очередном выполнении пакетной обработки.

OnExecuteError
procedure (pFIBQuery: TpFIBQuery; E: EFIBError; var Action: TdataAction);
Это событие генерируется при ошибке выполнения запроса.
Вызывается в случае, если выполнение запроса завершилось ошибкой. В нем можно проанализировать ошибку и подменить стандартный диалог об ошибке, какими-то другими действиями.

OnSQLChanging
procedure (Sender: Tobject);
Это событие вызывается при изменении текста SQL.

TransactionEnded
procedure (Sender: Tobject);
Это событие вызывается после завершения транзакции.

TransactionEnding
procedure (Sender: TObject);
Это событие вызывается при завершении транзакции.

Методы

function TableAliasForField(FieldIndex:integer):string;
 function TableAliasForField(const aFieldName:string):string;

Эти методы возвращают псевдоним таблицы для поля по индексу поля либо по его имени.

function BatchInput(InputObject: TFIBBatchInputStream) :boolean;
 function BatchOutput(OutputObject: TFIBBatchOutputStream):boolean; 
procedure BatchInputRawFile(const FileName:string);
procedure BatchOutputRawFile(const FileName:string;Version:integer=1); 
procedure BatchToQuery(ToQuery:TFIBQuery;Mappings:TStrings);

Методы пакетной обработки.Подробнее о методах для пакетной обработки читайте в разделе "Выполнение SQL-Запросов. Пакетная обработка" Руководства пользователя.

procedure CheckValidStatement;
Этот метод проверяет SQL на валидность.

procedure Close;
Этот метод закрывает запрос.

function Current: TFIBXSQLDA;
Этот метод возвращает буфер текущей записи.

procedure ExecQuery; virtual;
Этот метод выполняет запрос.

procedure FreeHandle;
Освобождает ресурсы сервера ассоциированные с данным запросом. Этот метод закрывает запрос с флагом DSQL_drop. При этом Handle запроса на сервере уничтожается и повторно его использовать уже нельзя.

function Next: TFIBXSQLDA;
Этот метод производит fetch следующей записи.

procedure Prepare;
Производит подготовку запроса к выполнению. Если этот метод не вызван явно, то он будет вызван автоматически во время выполнения запроса. Данные функции аналогичны одноименным функциям TpFIBDataSet: Работа с полями запроса

function FieldName(FieldIndex:integer):string;
Этот метод возвращает поле по индексу.

function FieldsCount:integer;
Этот метод возвращает количество полей.

function FieldExist(const FieldName:string; var FieldIndex:integer):boolean;
Этот метод проверяет существование поля с именем FieldName.

function FieldCount:integer;
Этот метод возвращает количество полей запроса.

function FieldByName(const FieldName: string): TFIBXSQLVAR;
Возвращает ссылку на поле запроса по имени FieldName. Если поля с таким именем в коллекции полей запроса отстутствует, то генерируется ошибка.

function FindField(const FieldName: string): TFIBXSQLVAR;
function FN(const FieldName: string): TFIBXSQLVAR;
Возвращает ссылку на поле запроса по имени FieldName. Если поля с таким именем в коллекции полей запроса отстутствует, то возвращается значение nil.

function FieldByOrigin(const TableName,FieldName:string):TFIBXSQLVAR; overload;
Возвращает ссылку на поле запроса по имени таблицы, которой оно принадлежит (TableName) и имени поля в таблице (FieldName). Если такого поля в коллекции полей запроса отстутствует, то возвращается значение nil. Следует так же обратить внимание, что для диалекта 3, все имена таблиц и полей регистрочувствительные. Как следствие, в этот метод надо передавать имена таблицы и поля в том регистре, в котором они созданы в БД.

Рассмотрим вышеупомянутые функции на примере нижеследующего кода:

var
F:TFIBXSQLVAR begin
pFIBQuery1.SQL.Text:=’Select Field1 F1 from Table1 T’;
 pFIBQuery1.ExecQuery; F:= pFIBQuery1.Fields[0]; 
F:= pFIBQuery1.FieldByName(’F1’); F:= pFIBQuery1.FindField (’F1’); 
F:= pFIBQuery1.FieldByOrigin(’TABLE1’,’FIELD1’); 
end;

Во всех случаях, в переменную F попадает ссылка на поле F1 запроса. Обратите внимание, что в последнем вызове мы передавали имя поля и таблицы в верхнем регистре.

procedure PrepareArrayFields;
procedure PrepareArraySqlVar( SqlVar:TFIBXSQLVAR;const RelName,SQLName:string; IsField:boolean );
Подробнее см. тему В« Работа с полями-массивамиВ» в Руководстве пользователя.

procedure SetParamValues(const ParamValues: array of Variant); overload; 
procedure SetParamValues(const ParamNames: string;
ParamValues: array of Variant); overload;
procedure ExecWP(const ParamValues: array of Variant); overload; 
procedure ExecWP(const ParamNames: string;ParamValues: array of Variant); overload; 
procedure ExecWPS(const ParamSources: array of ISQLObject);

Методы позволяют выполнить запрос и одновременно передать параметры этого запроса на сервер. Подробнее см. тему В«Заполнение параметровВ» в Руководстве пользователя.

function IsProc :boolean;
Этот метод установлен в True, если текст SQL - это выполнение процедуры (execute procedure xxx).

procedure RestoreMacroDefaultValues;
Этот метод устанавливает значения макросов в значения по умолчанию.

function ParamByName(const ParamName:string): TFIBXSQLVAR;
Этот метод возвращает параметр по его имени. Если параметра с таким именем в коллекции параметров запроса отстутствует, то генерируется ошибка.

function FindParam (const aParamName: string): TFIBXSQLVAR;
Этот метод ищет параметр по имени (в том числе и в макросах), Если параметра с таким именем в коллекции параметров запроса отстутствует, то возвращается значение nil.

function ParamCount:integer;
Этот метод возвращает количество параметров.

function ParamName(ParamIndex:integer):string;
Этот метод возвращает параметр по индексу.

function ParamExist(const ParamName:string; var ParamIndex:integer):boolean;
Этот метод проверяет существование параметра с именем ParamName.
Подробнее см. тему В«Заполнение параметровВ» в руководстве пользователя.

function FieldValue(const FieldName:string;Old:boolean):variant; overload; 
function FieldValue(const FieldIndex:integer;Old:boolean):variant; overload;
function ParamValue(const ParamName:string):variant; overload;
function ParamValue(const ParamIndex:integer):variant; overload; 

Этот метод возвращает значения полей и параметров

function ReadySQLText(ForChangeExecSQL:boolean=True): string;
Этот метод возвращает реальный текст SQL, который уходит на сервер при использовании
параметров и макросов.

procedure BeginModifySQLText;
procedure EndModifySQLText;
function CountModifySQLText:integer;
Следует отметить, что если включено свойство ParamCheck, то, как только разработчик меняет текст SQL, FIBPlus немедленно пытается отпарсить текст, для того, чтобы создать список параметров. Вышеописанные методы позволяют отложить процесс парсинга, если текст SQL сформировывается не одноразовой операцией, а несколькими. Например:

begin
pFIBQuery1.BeginModifySQLText;
try
pFIBQuery1.SQL.Clear;
pFIBQuery1.SQL.Add(’Insert into Table1 (ID,Name)’);
pFIBQuery1.SQL.Add(’Values(:ID,:NAME)’);
finally
pFIBQuery1.EndModifySQLText;
end end;

В этом примере парсинг запроса произойдет один раз, после вызова pFIBQuery1.EndModifySQLText. Если бы мы не вызывали бы метод BeginModifySQLText перед изменением текста, то парсинг происходил бы после каждой операции.

procedure AssignProperties(Source: TFIBQuery);
Этот метод копирует все свойства компонента-параметра

procedure ExecuteImmediate;
Запускает выполнение запроса без предварительной препарации. Все ресурсы необходимые для выполнения этого запроса будут созданы самим сервером и им же освобожднены. Этим методом можно выполнять только запросы не имеющие параметров.

procedure ExecProcedure(const ProcName:string);
Выполняет сохраненную процедуру по имени ProcName без параметров. Т.е. автоматически формируется тектс запроса вида : ’Execute Procedure ’+ ProcName и он запускается на выполнение.

procedure ExecProcedure(const ProcName:string;const InputParams:array of variant );
Выполняет сохраненную процедуру по имени ProcName с параметрами InputParams.

procedure ExecuteAsBatch;
procedure ExecuteAsBatch(const SQLs:array of string);
Выполняет пакет запросов. Работает только под IB2007 вызывая API функцию isc_dsql_batch_execute_immed

Public свойства

property Bof: Boolean read FBOF;
Это свойство установлено в True, если достигнуто начало набора данных.

property DBHandle: PISC_DB_HANDLE read GetDBHandle;
Это свойство возвращает Handle запроса.

property Eof: Boolean read GetEOF;
Это свойство установлено в True, если достигнут конец выборки

property FldByName[const FieldName: string]: TFIBXSQLVAR read FieldByName;
Это свойство возвращает значение поля по имени.

property Fields[const Idx: Integer]: TFIBXSQLVAR read GetFields;
Это свойство возвращает значение поля по индексу.

property FieldIndex[const FieldName: string]: Integer read GetFieldIndex;
Это свойство возвращает индекс поля по имени.

property Open: Boolean read Fopen;
Это свойство показывает, активен ли запрос.

property Params: TFIBXSQLDA read GetSQLParams;
Это свойство возвращает массив параметров запроса.

property OnlySrvParams:TStringList;
Это свойство возвращает список имен параметров запроса. В список попадают только те параметры которые реально будут использоваться параметры отправляемого запроса. Например для В«Select * from @@Table@В» свойcтво вернет пустой список, поскольку макрос не является параметром конечного запроса..

property Plan: string read GetPlan;
Это свойство возвращает план выполнения запроса.

property Prepared: Boolean read Fprepared;
Это свойство установлено в True, если запрос подготовлен на сервере.

property RecordCount: Integer read GetRecordCount;
Это свойство возвращает количество отфетченных записей.

property RowsAffected: Integer read GetRowsAffected;
Это свойство возвращает количество записей, измененных запросом.

property AllRowsAffected: TAllRowsAffected read GetAllRowsAffected;
Это свойство возвращает количество операций, произведенных запросом.

TAllRowsAffected = record
Updates: integer;
Deletes: integer;
Selects: integer;
Inserts: integer; end;

property SQLType: TFIBSQLTypes read FSQLType;
TFIBSQLTypes = (SQLUnknown, SQLSelect, SQLInsert, SQLUpdate, SQLDelete, SQLDDL, SQLGetSegment, SQLPutSegment, SQLExecProcedure, SQLStartTransaction, SQLCommit, SQLRollback, SQLSelectForUpdate, SQLSetGenerator, SQLSavePointOperation)

property TRHandle: PISC_TR_HANDLE read GetTRHandle;
Это свойство возвращает Handle – внутренний дескриптор транзакции на сервере, который идентифицирует каждую операцию с БД, сообщая, в рамках какой транзакции приходят запросы. Подробности смотрите в APIGuide.pdf

property ProcExecuted: boolean read FProcExecuted write FprocExecuted;
Это свойство установлено в True, если процедура в запросе выполнена через execute
procedure.

property OnSQLFetch: TOnSQLFetch read FOnSQLFetch write FonSQLFetch; TOnSQLFetch = procedure (RecordNumber:integer; var StopFetching:boolean ) of object;
Это свойство генерируется при fetch очередной записи.

property CursorName : string read FCursorName write FcursorName;
Это свойство возвращает имя курсора. Необходимо только для запросов типа Select for update.

property OrderClause: string read GetOrderString write SetOrderString;
Это свойство возвращает секцию order by

property GroupByClause: string read GetGroupByString write SetGroupByString;
Это свойство возвращает секцию group by

property FieldsClause: string read GetFieldsClause write SetFieldsClause;
Это свойство возвращает секцию полей

property PlanClause: string read GetPlanClause write SetPlanClause;
Это свойство позволяет задать план выполнения запроса.

property SQLKind: TSQLKind read GetSQLKind;
TSQLKind = (skUnknown, skSelect, skUpdate, skInsert, skDelete, skExecuteProc, skDDL, skExecuteBlock);

Еще одно свойство возвращающее тип запроса. В отличие от SQLType, оно доступно сразу же при присвоении текста SQL.