2.3.6. Макросы выборки

Список макросов
&DefUniFltMacros &ServFilterAliasMacros &GroupMacros
&DefUniFltMacrosRO &LoadData# &SortOrder#

Для управления запрашиваемыми с сервера данными в GST используются предопределенные макросы выборки, далее просто “макросы”. Макросы обеспечивают работу серверной фильтрации, сортировки, группировки, а также позволяют полностью предотвратить загрузку данных на клиент. Все макросы могут быть добавлены на уровне прикладной логики. Некоторые добавляются самим клиентом, если они отсутствуют в исходном запросе, но в выборке используются зависящие от них свойства.

Шаблон запроса формируемый клиентом включающий все макросы
select * from (
  select &ServFilterAliasMacros.* from (
    select * from (
      select * from dual where &GroupMacros) -- исходный запрос
    where &LoadData#) &ServFilterAliasMacros
  where &DefUniFltMacros and &DefUniFltMacrosRO) &SortOrder#

&GroupMacros не добавляется клиентом автоматически и приводится в части оригинального запроса для наглядности.

Attention

При использовании курсорных запросов, макросы могут быть добавлены только на уровне прикладной логики. Отсутствие макросов нарушит работу базирующегося на наих функционала.

Caution

Макросы должны размещаться таким образом чтобы минимизировать нагрузку на сервер.

Пример непреднамеренного повышения нагрузки на сервер
select * from (
  select * from dual &SortOrder#) -- исходный запрос с сортировкой
where &DefUniFltMacros -- фильтрация добавляемая клиентом и применяемая к уже отсортированным данным

2.3.6.1. Параметры вместо макросов

Иногда использование макросов в запросе недоступно или затруднительно. Например когда курсорный запрос возвращается результатом другого запроса. В таких случаях вместо макросов следует использовать одноименные параметры. При наличии этих параметров в них дублируется значение макросов.

Пример получения курсорного запроса с использованием параметров вместо макросов
[cursor cur]
begin
  :cur = btkgetrequest(:DefUniFltMacros, :DefUniFltMacrosRO, :ServFilterAliasMacros, :LoadData#, :GroupMacros, :SortOrder#);
end;

2.3.6.2. Макросы фильтрации

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

See also

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

select &ServFilterAliasMacros.*
from ('исходный запрос') &ServFilterAliasMacros
where &DefUniFltMacros and &DefUniFltMacrosRO

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

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

&DefUniFltMacros и &DefUniFltMacrosRO добавляются клиентом в GST при выполнении следующих условий:

  1. Они отсутствуют в исходном запросе;
  2. Соответствующие им значения непусты или запрос начинается с макроса &ServFilterAliasMacros.

&ServFilterAliasMacros добавляется клиентом в GST при выполнении следующих условий:

  1. Значение макроса непусто. Недопустим запрос select .* from table (с пустотой перед ‘.*’);
  2. В исходном запросе не встречается ни один из макросов фильтрации. Их использование недопустимо внутри обертки с Alias.

&DefUniFltMacros

Значение &DefUniFltMacros формируется на основе условий фильтрации налагаемых универсальным фильтром, а также условий формируемых в событиях фильтрации. Если макрос не добавлен в некурсорный GST на прикладном уровне, клиент добавит его автоматически но только при наличии условий фильтрации. Если макрос в GST присутствует, но соответствующее ему значение пустое, вместо него подставляется (2=2).

&DefUniFltMacrosRO

&DefUniFltMacrosRO содержит значение указанное в UniFilterMacrosRO. Если макрос не добавлен в некурсорный GST на прикладном уровне, клиент добавит его автоматически но только при наличии значения у UniFilterMacrosRO. Если макрос в GST присутствует, но соответствующее ему значение пустое, вместо него подставляется (2=2).

&ServFilterAliasMacros

&ServFilterAliasMacros содержит значение Alias для GST. Значение возвращается событием фильтрации OnFilterInit. Если макрос в GST присутствует, но соответствующее ему значение пустое, вместо него подставляется пустая строка.

Attention

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

2.3.6.3. Макросы управления загрузкой

&LoadData#

See also

LoadDataOnFirstOpen

&LoadData# используется для предотвращения загрузки данных если не установлено свойство LoadDataOnFirstOpen, а также при прерывании продолжительных запросов. Управление загрузкой осуществляется с помощью установки значения макроса в заведомо ложное условие фильтрации (1=2), когда необходимо предотвратить загрузку и заведомо справедливое - (2=2), когда предотвращение не требуется. Макрос &LoadData# добавляется ко всем некурсорным GST автоматически, если он отсутствует в исходном GST.

Warning

Если &LoadData# отсутствует в GST то при прерывании длительного запроса пользователем выборка будет закрыта. При этом функционал применения фильтров работать перестанет, что помешает пользователю наложить условия фильтрации на следующее открытие выборки.

2.3.6.4. Макросы группировки

&GroupMacros

See also

&GroupMacros добавляется в GST для использования серверной группировки.

Пример:
SELECT
    t.ID
    , t.idGroup, BTK_ClientGate.GetHeadLineGroup(t.idGroup) AS idGroup_HL
    , t.sCAPTION
    , t.sSystemName
    , t.idClass
  FROM GroupPanelTest t
  WHERE
    &GroupMacros

Caution

&GroupMacros не добавляестся клиентом автоматически и при необходимости должен добавляться на прикладном уровне.

2.3.6.5. Макросы сортировки

See also

&SortOrder#.

&SortOrder# используется для добавления к GST выражения сортировки. Значение макроса формируются на основе настроек сортировки установленных пользователем и представляет собой строку вида order by AttrName1, AttrName2 .... Если макрос не добавлен в некурсорный GST на прикладном уровне, клиент добавит его автоматически но только в случае если пользователем были установлены настройки сортировки. Если макрос в GST присутствует, но соответствующее ему значение пустое, вместо него подставляется пустая строка.

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

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

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