3.3.5. Параметры выборки

3.3.5.1. Имена параметров

3.3.5.1.1. Служебные префиксы

Для доступа к параметрам используются следующие префиксы:

• super$, - параметры мастера;
• old$, - предыдущее значение. Используется только для чтения и не может использоваться для установки значений;
• filter$, - параметры фильтрации выборки.

При обращении к параметрам допускается также использование комбинаций префиксов со следующими ограничениями:

1. префикс super$ может использоваться несколько раз, но должен всегда находиться перед именем параметра и другими префиксами;
2. префикс old$ может использоваться только один раз, должен находиться перед именем параметра и префиксом filter$, если таковой имеется;
3. префикс filter$ может встречаться только один раз и указываться непосредственно перед именем параметра.

Примеры:¶

<pascal>

  id1 := GetVar('id'); //получение значения параметра 'id' текущей выборки

  id2 := GetVar('super$id'); //получение значения параметра 'id' мастер-выборки

  id3 := GetVar('super$super$id'); //получение значения параметра 'id' мастер-выборки мастер-выборки

  flt1 := GetVar('filter$flt'); //получение значения параметра фильтрации 'flt' текущей выборки

  flt2 := GetVar('super$filter$flt'); //получение значения параметра фильтрации 'flt' мастер-выборки

  flt2OldValue := GetVar('super$old$filter$flt'); //получение предыдущего значения параметра фильтрации 'flt' мастер-выборки

</pascal>

Служебные префиксы используются только для получения доступа к уже существующим параметрам и не могут использоваться при создании новых параметров. При необходимости создать внутренний параметр в мастере выборки используйте свойство 'Master'.

Примеры:¶

<pascal>

  Selection.Master.AddVar('param1', 'value', ftString); //Правильно

  Selection.AddVar('super$param1', 'value', ftString); //Неправильно

</pascal>

3.3.5.2. Типы параметров

TFieldType	Описание	Примечание, допустимые значения
ftUnknown	неизвестный / не определённый тип	Используется для добавления параметров, тип которых будет определён по значению
ftString	символ или строка
ftSmallInt	16-битное целое число	-32767..32768
ftInteger		в Global эквивалентен типу ftFloat
ftWord	16-битное беззнаковое целое число	0..65535
ftBoolean		false, true; 0, 1; при установке значения, отличного от перечисленных, будет установлено true
ftFloat	число с плавающей точкой
ftCurrency	денежный тип
ftBCD
ftDate	дата
ftTime	время
ftDateTime	дата и время
ftBytes
ftVarBytes
ftAutoInc
ftBlob
ftMemo
ftGraphic
ftFmtMemo
ftParadoxOle
ftDBaseOle
ftTypedBinary
ftCursor
ftFixedChar
ftWideString
ftLargeInt
ftADT
ftArray
ftReference
ftDataSet
ftOraBlob
ftOraClob
ftVariant	Данные, не привязанные к определённому типу данных
ftInterface
ftIDispatch
ftGuid
ftTimeStamp
ftFMTBcd

3.3.5.3. Стойкость параметров

Параметры выборки могут быть "стойкие" (persistent) или "не стойкие" (по умолчанию). Если параметр является стойким, то при закрытии выборки он сохранит свое значение и восстановит его при новом открытии этой выборки, после вызовов OnLoadMeta, OnFilterInit, до вызова BeforeOpen. При закрытии датасета и новом открытии настройки заново не загружаются. У процедуры создания параметров выборки TbtkScriptSelectionObject.AddVar есть параметр APersistence, который указывает, является ли параметр стойким, а также задаёт место, где будет храниться значение параметра.

procedure TbtkScriptSelectionObject.AddVar(

  AName: String;

  AValue: Variant;

  AType: Variant;

  APersistence: TbtkPersistentType default ptNone);

Параметр APersistence имеет тип TbtkPersistentType. Описание принимаемых им значений:

• ptNone — параметр не является "стойким" и будет удален при закрытии выборки. Является значением по умолчанию.
• ptRegistry — параметр является "стойким", после закрытия выборки его значение будет сохранено в реестре приложения, а при открытии выборки — восстановлено оттуда.

Пример:

<pascal>

  AddVar('PersistVar', 'DefaultValue', ftString, ptRegistry);

<pascal>

3.3.5.4. Алгоритм поиска параметров

При обращении к параметрам через паскаль операции используется следующий алгоритм поиска параметра:

• имя параметра начинается с префикса 'super$'

отбрасываем префикс, ищем параметр в мастере

• имя параметра начинается с префикса 'filter$'

отбрасываем префикс, ищем в параметрах фильтрации

если параметр не найден

ищем параметр в мастере

• ищем в атрибутах выборки

если параметр не найден

ищем в параметрах фильтрации

• ищем во внутренних параметрах

если параметр не найден

ищем параметр в мастере

3.3.5.5. Методы паскаль операций

3.3.5.5.1. VarExists

Для проверки существования параметров используется функция VarExists.

procedure VarExists(AName: string);

3.3.5.5.2. SelfVarExists

3.3.5.5.3. AddVar

Для добавления внутренних параметров выборки используется метод AddVar.

procedure AddVar(

  AName: string;

  AValue: Variant;

  ADataType: TFieldType;

  APersistent: TbtkPersistentType);

• ADataType - тип добавляемого параметра;
• APersistent - флаг стойкости параметра.

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

Примеры корректного вызова:¶

  <pascal>

    Selection.AddVar('var1', 'Value', ftString, ptRegistry); //добавление строкового стойкого параметра в текущую выборку

    AddVar('id', 123, ftInteger, ptNone); //добавление не стойкого целочисленного параметра в текущую выборку

    CustomSel.AddVar('anyVar', null, ftUnknown); //добавление не стойкого параметра типа ftUnknown в выборку "CustomSel"

  <pascal>

Примеры некорректного вызова:¶

  <pascal>

    Selection.AddVar('Var1', 'Value', ftFloat); //задаваемое значение ('Value') невозможно представить в указанном типе (ftFloat)

    AddVar('', 123, ftInteger); //не указано имя параметра

    CustomSel.AddVar('super$anyVar', null, ftUnknown); //в имени параметра используется зарезервированный префикс 'super$'

  <pascal>

3.3.5.5.4. SetVar

Метод SetVar используется для установки значений:

• внутренним параметрам;
• параметрам фильтрации;
• полям выборки.

3.3.5.5.5. GetVar

3.3.5.5.6. GetSelfVar

3.3.5.5.7. SetVarDesc

3.3.5.5.8. GetVarDesc

3.3.5.6. Макросы выборок

3.3.5.6.1. Макросы фильтрации и условия Alias

&DefUniFltMacros	Макрос универсального (серверного) фильтра выборки
&DefUniFltMacrosRO	Условие, дописываемое к условию макроса &DefUniFltMacros
&ServFilterAliasMacros	Макрос условия Alias
&LoadData#	Используется, если установлено свойство выборки "Не загружать данные при первом открытии"

Эти макросы используются для "оборачивания" исходного запроса данных следующим образом:

select ServFilterAliasMacros.*

from (<исходный запрос>) &ServFilterAliasMacros

where &DefUniFltMacros and &DefUniFltMacrosRO

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

Условия добавления макросов:

&ServFilterAliasMacros - добавляется с оборотом запроса только в случае, если выполнены следующие условия:

1. значение макроса непусто (недопустим запрос *select .* from ... * с пустотой перед '.');
2. в исходном запросе еще не встречается ни один из трех указанных макросов (недопустимо использование макросов фильтрации внутри обертки Alias).

&DefUniFltMacros и &DefUniFltMacrosRO независимо дописываются, если:

1. они ещё не встретились в исходном запросе;
2. соответствующие им значения непусты или запрос начинается с макроса Alias.

Примечание:

&ServFilterAliasMacros заполняется (может быть прописан в запросе вручную) только при активных операциях универсального фильтра.

Об использовании макросов фильтрации и операций серверного фильтра см. в статье: http://wiki.gs.local/index.php/Фильтрация_серверая#Паскаль-события_фильтрации>

3.3.5.6.2. Макросы сортировки:

&SortOrder#

Макрос сортировки

Макрос сортировки, содержащий накладываемые фильтрами значения. Подробнее см. в статье:http://wiki.gs.local/index.php/Сортировка_серверная

3.3.5.6.3. Свойства выборки, отключающие применение макросов фильтрации и сортировки:

ApplyServFilterMacros	Свойство отвечает за наложение макросов фильтрации &DefUniFltMacros и &DefUniFltMacrosRO. По умолчанию включено - значения макросов накладываются при запросе данных. Если свойство выключить, значения макросов все равно соответствуют настройкам фильтров, однако на формирование запроса не влияют.
ApplyServSortOrderMacros	Аналогичное свойство, отвечающее за применение макроса сортировки &SortOrder#.

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

3.3.5.6.4. Смена макросов и переоткрытие выборки

Во избежание лишних переоткрытий датасета, решено поддерживать следующую логику при смене значений макросов:

1. при добавлении нового макроса, или смене значения макроса, не входящего в GST, ничего не происходит.
2. при смене значения макроса, входящего в текст запроса, выполняется переоткрытие выборки (если не установлено свойство "Не закрывать датасет при обновлении макроса").