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

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

2.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>

2.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    

Для возможности осуществления корректного сравнения значений параметров, непосредственно сами значения (Value: Variant) приводятся к типу соответствующему типу данных параметра.

Таблица соответствия типов:

TFieldType TVarType
ftUnknown varEmpty
ftString varString
ftSmallint varInteger
ftInteger varInteger
ftWord varInteger
ftBoolean varBoolean
ftFloat varDouble
ftCurrency varCurrency
ftBCD varCurrency
ftDate varDate
ftTime varDate
ftDateTime varDate
ftBytes varEmpty
ftVarBytes varEmpty
ftAutoInc varInteger
ftBlob varEmpty
ftMemo varString
ftGraphic varEmpty
ftFmtMemo varEmpty
ftParadoxOle varEmpty
ftDBaseOle varEmpty
ftTypedBinary varEmpty
ftCursor varEmpty
ftFixedChar varString
ftWideString varOleStr
ftLargeint varEmpty
ftADT varEmpty
ftArray varEmpty
ftReference varEmpty
ftDataSet varEmpty
ftOraBlob varEmpty
ftOraClob varEmpty
ftVariant varVariant
ftInterface varUnknown
ftIDispatch varDispatch
ftGuid varString
ftTimeStamp varEmpty
ftFMTBcd varEmpty

Если типу данных соответствует тип значения varEmpty, то значение будет присвоено “как есть”, без приведения его к varEmpty. В случае если значение не может быть представлено в соответствующем с типом данных виде будет сгенерировано исключение.

В случаях когда тип данных параметра указан как ftUnknown, он будет определён после того как параметру присвоят значение, отличное от null, unassigned и varEmpty, в соответствии со следующей таблицей:

TVarType TFieldType
varSmallint ftSmallInt
varShortInt ftSmallInt
varByte ftSmallInt
varWord ftInteger
varInteger ftInteger
varCurrency ftBCD
varLongWord ftFloat
varSingle ftFloat
varDouble ftFloat
varDate ftDateTime
varBoolean ftBoolean
varString ftString
varOleStr ftString
varInt64 ftLargeInt
varSQLTimeStamp ftTimeStamp
varFMTBcd ftFMTBcd
Все остальные ftUnknown

После добавления, или загрузки внутренние параметры будут существовать на протяжении всей жизни экземпляра объекта выборки, и уничтожатся только при его разрушении. Закрытие или обновление (Refresh) выборки не приведёт к уничтожению уже добавленных параметров, вне зависимости от того являются они стойкими или нет. В текущей реализации также отсутствует возможность удаления параметров, а это значит что однажды добавленные стойкие параметры всегда будут в ней присутствовать. Для удаления таких параметров можно использовать возможность их повторного добавления с указанием того что они являются не стойкими. После этого они больше не будут сохраняться при закрытии и восстанавливаться при открытии выборки.

2.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>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

2.3.5.5.1. VarExists

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

procedure VarExists(AName: string);

2.3.5.5.2. SelfVarExists

2.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>

2.3.5.5.4. SetVar

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

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

2.3.5.5.5. GetVar

2.3.5.5.6. GetSelfVar

2.3.5.5.7. SetVarDesc

2.3.5.5.8. GetVarDesc

2.3.5.6. Служебные параметры

Раздел находится в разработке.

Пока описаны не все параметры.

Параметр Доступ Описание Значение по умолчанию
Caption Чтение и запись Основная часть заголовка фрейма DisplayName
CaptionExt Чтение и запись Расширение заголовка фрейма ‘’