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. при смене значения макроса, входящего в текст запроса, выполняется переоткрытие выборки (если не установлено свойство "Не закрывать датасет при обновлении макроса").