Методы быстрого доступа к Selection
``````````````````````````````````````````````````````````````````````

Контекст/Параметры/Данные
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

.. pas:function:: GetVar(Name: String): Variant

  Возвращает значение атрибута (параметра).

  :param String Name:
    Имя параметра.

  :rtype: Variant

.. seealso::
  :ref:`common_frame_properties`.

.. pas:function:: VarExists(Variant: Variant): Boolean

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

  :param Variant Variant:
    Имя параметра выборки или парамлиста

  :rtype: Boolean


.. pas:function:: ClientSetVar(Name: String; Value: Variant)

  Метод работает аналогично ``SetVar``, устанавливает значение атрибута
  (параметра), но без вызова сеттера.

  :param String Name:
    Имя атрибута(параметра).

  :param Variant Value:
    Значение атрибута(параметра).


.. pas:function:: AddVar(Name: String; Value: Variant; Type: TFieldType)

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

  :param String Name:
    Имя создаваемого параметра

  :param Variant Value:
    Значение параметра.

  :param TFieldType Type:
    Тип данных параметра


.. pas:function:: SetVarDesc(Name, Value: Variant)

  Устанавливает описание параметра (то, что отображается в заголовках
  грида и т.п.). В *Value* можно передать заголовок бенда, к которому будет
  привязан атрибут (через символ \|)

  :param Variant Name:
    Имя параметра.

  :param Variant Value:
    Cтрока описания.


.. pas:function:: GetSelfVar(VarName: String): Variant

  Возвращает значение параметра выборки. В отличае от ``GetVar`` не смотрит
  на выборку мастера, если не находит параметр *VarName* в текущей выборке.
  С помощью данной функции можно получить значения:

  - атрибута выборки
  - свойства фрейма
  - параметры добавленные с помощью ``AddVar``
  - параметры добавленные при вызове ``CreateFormEx`` или ``DoLookUpEx``.

  :param String VarName:
    Имя переменной.

  :rtype: Variant


.. pas:function:: GetVarDesc(Name: String): String

  Получает описание параметра (то, что отображается в заголовках списка и
  т.п.)

  :param String Name:
    Имя параметра.

  :rtype: String


.. pas:function:: SelfVarExists(VarName: Boolean): Variant

  Проверяет существование параметра выборки. В отличии от ``VarExists``, не
  смотрит на выборку мастера, если не находит параметр *VarName* в текущей
  выборке. С помощью данной функции можно проверить существование:
  - атрибута выборки
  - свойства фрейма
  - параметры добавленные с помощью ``AddVar``
  - параметры добавленные при вызове ``CreateFormEx`` или ``DoLookUpEx``.

  :param Boolean VarName:
    Имя переменной.

  :rtype: Variant


.. pas:function:: SetVar(ParamName: String; ParamValue: Variant)

  Устанавливает значение атрибута (параметра).

  :param String ParamName:
    Имя параметра.

  :param Variant ParamValue:
    Строка описания.


Макросы
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

.. pas:function:: GetMacro(MacroName: String): String

  Метод возвращает значение макроса с именем *MacroName*.

  :param String MacroName:
    Имя макроса

  :rtype: String


.. pas:function:: IsMacroExists(MacroName: String): Boolean

  Проверяет существование макроса c именем *MacroName*.

  :param String MacroName:
    Имя макроса.

  :rtype: Boolean

  .. code-block:: delphi
    :caption: Пример использования

    <pascal>
      if IsMacroExists('NewMacro') then
        SetMacro('NewMacro', 'Select 2 from dual')
      else
        AddMacro('NewMacro', 'Select 2 from dual');

      ShowMessage(GetMacro('NewMacro'));
      Selection.Active := False;
      Selection.Active := True;
    </pascal>

.. pas:function:: SetMacro(MacroName, MacroValue: String): Variant

  Устанавливает макрос с именем *MacroName* и значение *MacroValue*. Если
  при установке значения макроса выборка была открыта (``Selection.Active =
  True``), то произойдёт её закрытие. Поэтому после установки макроса
  необходимо открыть выборку самостоятельно.

  :param String MacroName:
    Имя макроса

  :param String MacroValue:
    Значение макроса

  :rtype: Variant


.. pas:function:: AddMacro(MacroName, MacroValue: String)

  Создаёт в выборке макрос с именем *MacroName* и значением *MacroValue*.
  Если макрос с именем *MacroName* существует, макросу будет установлено
  значение *MacroValue*.

  :param String MacroName:
    Имя макроса.

  :param String MacroValue:
    Значение макроса.


Датасет
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

.. pas:function:: Commit()

  Шорткат метода :pas:meth:`TbtkScriptSelectionObject.Commit`.


.. pas:function:: Append(F: Variant)

  Функция открывает файл на добавление записей в файл.

  :param Variant F:
    Файловая переменная.

  .. warning:: |not_implemented|

.. pas:function:: Change()

  Вызов метода указывает форме, что данные на форме менялись, даже если
  транзакция не была начата


.. pas:function:: Rollback()

  Функция вызывает откат текущей активной транзакции.


.. pas:function:: BlobOpen(FieldName, Extension, Wait, Save: Variant): Boolean

  Запускает приложение, ассоциированное с расширением *Extension*, передает
  ему данные из поля выборки *FieldName* и, если ``Wait = true``, то ожидает
  завершения запущенного приложения, после чего сохраняет или нет (в
  зависимости от параметра *Save*) обратно в БД. Возвращает *True* если
  изменения в файле были сохранены в поле.

  :param Variant FieldName:
    Имя поля.

  :param Variant Extension:
    Расширение файла (с точкой впереди).

  :param Variant Wait:
    Ожидать ли завершения запущенного приложения.

  :param Variant Save:
    Имеет смысл только если параметр ``Wait = true``. Сохранять ли файл в БД если
    он был изменен:

    stTrue
      сохранить

    stFalse
      не сохранять

  :rtype: Boolean


.. pas:function:: GetFocusedFieldName(): String

  Возвращает имя атрибута (параметра), на редакторе которого находится
  фокус. Для списка (дерева) – это будет активный столбец; для карточки
  (панели фильтров) – это атрибут (параметр), редактируемый активным
  контролом. Если что-то не так, вернёт пустую строку.

  Метод является алиасом для :pas:class:`TbtkScriptSelectionObject.GetFocusedFieldName`

  :rtype: String


.. pas:function:: BlobOpenEx(FieldName, FileName: String; Selection: TbtkScriptSelectionObject; Operation: String; Mode: TbtkWatcherMode): Boolean

  Добавлена возможность открывать на редактирование файлы хранящиеся в
  blob полях в немодальном режиме. В немодальном режиме файл можно
  открыть использую метод ``BlobOpenEx``. После завершения приложения будет
  вызвана операция выборки. Операция выборки вызовется только в случае
  если файл было измен. Возвращает *True* если изменения в файле были
  сохранены в поле.

  :param String FieldName:
    Имя поля типа blob с файлом.

  :param String FileName:
    Имя файла. Можно передать:

    - Полный путь к файлу (C:\\Temp\\picture.jpg);

    - Имя файла (picture.jpg), тогда приложение попытается создать файл с
      таким именем во временном каталог пользователя;

    - Расширение файла (.jpg) - приложение попытается создать файл с
      уникальным именем и указанным расширением во временном каталоге
      пользователя.
      В случае, если такой файл уже существует, то будет возбуждено
      исключение.

  :param TbtkScriptSelectionObject Selection:
    Выборка в которой будет вызвана операция на событие завершение
    редактирования файла.

  :param String Operation:
    Имя операции которая будет вызвана при завершении редактирования файла.

  :param TbtkWatcherMode Mode:
    Режим открытия файла:

    - wmProcess - Определение того, что файл редактируется, производится на
      основе существования процесса приложения открывшего его. Как только
      процесс завершается, делается вывод, что редактрование завершено.
      Данный режим обладает недостатком. Если приложение(например MS Word)
      для открытия нескольких файлов использует один и тот же процесс, то
      процесс завершится после закрытия всех открытых файлов, чего следует
      избегать, и, по возможности, использовать следующий режим;

    - wmFile - Определение того, что файл редактируется, производится на
      основе того, что многие приложения занимают файл при открытии,
      недопуская его открытия на редактирование другим приложением. Но
      данный способ применим не ко всем приложениям (Например, приложение
      "Блокноте" не запрещает редактировать файл при открытии другим
      приложения).

    - wmAuto - авто-определения режима. В случае, если при вызове уже не
      запущен процесс приложения которым следует открыть файл, то будет
      выбран режим *wmProcess*, иначе режим *wmFile*


  :rtype: Boolean

  .. code-block:: delphi
    :caption: Пример использования

    <PASCAL>
      path := InputBox ('Введите путь файлу', 'Файл:', '');
      selection.blobopenex('blobFile',path ,selection,'SendEmail',wmFile);
    </PASCAL>


Forms
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

.. pas:function:: CreateForm(FormName, EntityName: String; FormType: TFormCreationFlags): TModalResult

  Метод создает и показывает форму.
  Если форма модальная, то функция ожидает её закрытия.

  :param String FormName:
    Имя формы.

  :param String EntityName:
    Имя выборки которая будет показана на форме.

  :param TFormCreationFlags FormType:
    Параметр определяет как будет показана форма (модально или как
    MDI-child).

  :rtype: TModalResult

  :returns:
    mrOk или mrCancel
      если форма модальная (``FormType = fcfModal``)

    mrNone
      если форма MDI-ная (``FormType = fcfMDI``)

  .. code-block:: delphi
    :caption: Пример использования

    <Pascal>
      CreateForm('', 'SEL_RPT_Report.List', fcfMDI);
    </Pascal>


.. pas:function:: CreateFormEx(FormName, EntityName: String; FormType: TFormCreationFlags; PropNames, PropValues: Array): TModalResult

  Метод создает и показывает форму.
  Если форма модальная, то функция ожидает её закрытия.
  Отличается от CreateForm возможностью передавать дополнительные параметры.

  При открытии :term:`Built-in <Built-in форма>` формы производит поиск существующей и её активацию (поиск делается по имени выборки, отображению, списку параметров выборки, переданных через CreateFormEx).
  После активации уже существовавшей формы вызывается операция OnFormActivatedAfterFindWindow.
  Для того, чтобы всегда открывать форму в новом окне, не проверяя, есть ли уже такая же открытая форма, в списке передаваемых параметров необходимо указать параметр CreatingMode со значением "CreateNewForm". 
  
  Также имеется возможность передавать в выборку макросы в качестве
  параметров. Макрос передается в списке параметров. Имя макроса должно начинаться с
  символа '&'.

  :param String FormName:
    Имя формы.

  :param String EntityName:
    Имя выборки которая будет показана на форме.

  :param TFormCreationFlags FormType:
    Параметр определяет как будет показана форма (модально или как
    MDI-child).

  :param Array PropNames:
    Массив имен параметров.

  :param Array PropValues:
    Массив значений параметров [APropNames].

  :rtype: TModalResult

  :returns:
    mrOk или mrCancel
      если форма модальная (``FormType = fcfModal``)

    mrNone
      если форма MDI-ная (``FormType = fcfMDI``)


  .. code-block:: delphi
    :caption: Примеры использования

    <Pascal>
      CreateFormEx('', 'SEL_RPT_Report.List', fcfMDI,
      ['Representation', 'TabVisible','ExParam1'],
      ['RoList', 0, 'Значение']);
    </Pascal>

    <Pascal>
      CreateFormEx('', 'SEL_RPT_Report.List', fcfMDI,
      ['Representation', '&macros','ExParam1'],
      ['RoList', 'cSum < 100', 'Значение']);
    </Pascal>

.. pas:function:: DoLookup(LookupControlClass, EntityName: String; LocateFieldNames, LocateFieldValues, ResultFieldNames: Array; MultiSelect: Boolean): TbtkLookupData

  Отображает выборку в режиме выбора (в lookup-форме), возвращает
  результат в виде набора записей :pas:class:`TbtkLookupData`.

  :param String LookupControlClass:
    Имя класса формы.

  :param String EntityName:
    Системное имя выборки (если пусто, то определяется вызываемой формой).

  :param Array LocateFieldNames:
    Массив имен атрибутов выборки по которым ищется запись для начального
    позиционирования.

  :param Array LocateFieldValues:
    Вариантный массив значений для *LocateFieldNames*.

  :param Array ResultFieldNames:
    Массив имен атрибутов выборки, значения которых будут возвращены как
    результат. В случае, если необходимо вернуть значение атрибута из
    детальной выборки, в качестве массивов имен атрибутов передаются имена
    состоящие из: ``[имя выборки].[имя поля]``.

  :param Boolean MultiSelect:
    Возможен ли выбор нескольких записей из выборки.

  :rtype: TbtkLookupData

  .. code-block:: delphi
    :caption: Пример использования

    <Pascal>
      R := DoLookup('TbtkLookupGridForm', 'maintree', ['id'], [2629000], ['id', 'sParentClass'], true);

      if R.LookupResult=lrOk then
        MessageDlg(VarToStr(R.Data(0,1)) + '->' + R.Data(1,1), mtWarning, 'mbYes', 0);
    </Pascal>


.. pas:function:: DoLookupEx(LookupControlClass, EntityName: String; LocateFieldNames, LocateFieldValues, ResultFieldNames: Array; MultiSelect: Boolean; PropNames, PropValues: Array): TbtkLookupData

  Отображает выборку в режиме выбора (в lookup-форме), возвращает
  результат в виде набора записей :pas:class:`TbtkLookupData`.

  Отличается от ``DoLookUp`` возможностью дополнительного указания свойств
  для открываемой формы.

  :param String LookupControlClass:
    Имя класса формы.

  :param String EntityName:
    Системное имя выборки (если пусто, то определяется вызываемой формой).

  :param Array LocateFieldNames:
    Массив имен атрибутов выборки по которым ищется запись для начального
    позиционирования.

  :param Array LocateFieldValues:
    Вариантный массив значений для *LocateFieldNames*.

  :param Array ResultFieldNames:
    Массив имен атрибутов выборки, значения которых будут возвращены как
    результат. В случае, если необходимо вернуть значение атрибута из
    детальной выборки, в качестве массивов имен атрибутов передаются имена
    состоящие из: ``[имя выборки].[имя поля]``.

  :param Boolean MultiSelect:
    Возможен ли выбор нескольких записей из выборки.

  :param Array PropNames:
    Массив имен свойств.

  :param Array PropValues:
    Массив значений свойств.

  :rtype: TbtkLookupData


  .. code-block:: delphi
    :caption: Пример использования, в котором рассматривается случай возврата значений из двух выборок.

    <SQL>
      <Set>
        begin
          AnyAPI.SetIdContract(:id, :IDContract);
          AnyAPI.SetIdContract(:id, :IDObligation);
        end;
      </Set>
    </SQL>

    <Pascal>
      S := DoLookupEx('', 'SELRO_CNT_ContractChoose',
      ['SELRO_CNT_ContractChoose.id',
      'SELROCL_CNT_ObligationChoose.id'],
      [GetVar('IDContract'), GetVar('IDObligation')],
      ['SELRO_CNT_ContractChoose.id',
      'SELROCL_CNT_ObligationChoose.id'], false,
      ['Caption'], [GetFmtCaption('CONTRACTOBLFORCHOOSE',
      [GetVar('super$IDSettlerOut_HL'), GetVar('super$IDSettlerIn_HL')])]);

      if S.LookupResult = lrOk then
      begin
        ShowMessage(s.SelectData('SELRO_CNT_ContractChoose').RecCount);
        ShowMessage(s.SelectData('SELROCL_CNT_ObligationChoose').RecCount);

        SetVar('IDContract', S.SelectData('SELRO_CNT_ContractChoose').Data[0,1]);
        SetVar('IDObligation', S.SelectData('SELROCL_CNT_ObligationChoose').Data[0,1]);
        ExecSql('set');
      end;
    </Pascal>

  Для доступа вернувшимся значениям была использована структура:
  ``SelectData([имя выборки]).Data [AttrNo,RecNo]``. Её использование
  необходимо при явном указании имени поля (``[имя выборки].[имя поля]``),
  если поле указано неявно (``[имя поля]``), то вернувшиеся данные будут
  доступны непосредственно в свойстве *Data*


.. pas:function:: CreatePanelEx(FrameName, EntityName: String; ParamNames, ParamValues: Array)

  Метод показывает фрейм в виде панели на текущей форме. Передает фрейму
  параметры. Существуют следующие параметры, позволяюще настроить
  создаваемый фрейм:

  PanelAlign
    Задает расположение панели. Допустимые значения:

    - alLeft
    - alTop
    - alBottom
    - alRight

    Если не указывать - будет alLeft.

  PanelSize
    Размер создаваемой панели. Высота, если ``align = alTop`` или
    ``align = alBottom``, и ширина в других случаях.
    По умолчанию = 1/3 от ширины/высоты экрана.

  :param String FrameName:
    Имя фрейма.

  :param String EntityName:
    Имя выборки, которой инициализируется внутренний *Selection* формы.

  :param Array ParamNames:
    Массив имен параметров.

  :param Array ParamValues:
    Массив значений параметров.

  .. code-block:: delphi
    :caption: Пример использования

    <pascal>
      CreatePanelEx('TBTKLOOKUPGRIDTABFRAME', 'SEL_ObjectClassUnion', [null], [null]);

      CreatePanelEx('TBTKLOOKUPGRIDTABFRAME', 'SEL_ObjectClassUnion', ['PanelAlign', 'PanelSize'], [alTop, 450]);
    </pascal>


TModalResult
..............

.. pas:class:: TModalResult

  Перечисление

  Результат, возвращаемый модальным окном при закрытии.

  .. pas:attribute:: mrYesToAll

    Окно закрыто кнопкой YES TO ALL.


  .. pas:attribute:: mrNoToAll

    Окно закрыто кнопкой NO TO ALL.


  .. pas:attribute:: mrAll

    Окно закрыто кнопкой ALL


  .. pas:attribute:: mrRetry

    Окно закрыто кнопкой RETRY.


  .. pas:attribute:: mrNo

    Окно закрыто кнопкой NO.


  .. pas:attribute:: mrYes

    Окно закрыто кнопкой YES


  .. pas:attribute:: mrAbort

    Окно закрыто кнопкой ABORT.


  .. pas:attribute:: mrCancel

    Окно закрыто кнопкой CANCEL.


  .. pas:attribute:: mrOk

    Окно закрыто кнопкой OK.


  .. pas:attribute:: mrNone

    Значение по-умолчанию. Задается при создании модалного окна.

  .. pas:attribute:: mrIgnore

    Окно закрыто кнопкой IGNORE

TLookUpResult
................

.. pas:class:: TLookUpResult

  Перечисление

  Результат выбора записей в lookup-форме.

  .. pas:attribute:: lrCancel

  .. pas:attribute:: lrOk


TFormCreationFlags
....................

.. pas:class:: TFormCreationFlags

  Перечисление

  .. pas:attribute:: fcfMDI

  .. pas:attribute:: fcfModal


Фреймы
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

.. pas:function:: Scheduler(): TbtkScheduler

  Возвращает объект-планировщик Scheduler.

  :rtype: TbtkScheduler

  .. warning:: |not_implemented|


.. pas:function:: Gantt(): TbtkGantt

  Метод возвращает ссылку на объект "График Гантта", расположенный на
  фрейме. Если на фрейме компонента "График Гантта" не существует, метод
  вернёт *null*.

  :rtype: TbtkGantt


.. pas:function:: Diagram(): TbtkAdvDiagram

  Возвращает объект для работы с Adv диаграммой, если он присутствует на фрейме. В противном случае вернёт *null*.

  :rtype: TbtkAdvDiagram


.. pas:function:: Chart(): TCustomChart

  Метод возвращает активный объект - график, типа :pas:class:`TCustomChart`.

  :rtype: TCustomChart

  .. warning:: |not_implemented|


.. pas:function:: Olap(): TbtkScriptOLAPObject

  Доступ к OLAP интерфейсу фрейма текущей выборки.

  :rtype: TbtkScriptOLAPObject


SQL
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

.. pas:function:: ExecSQL(BlockName: String)

  Метод выполняет PL/SQL-блок *BlockName*, объявленный в текущей операции.

  :param String BlockName:
    Имя PL/SQL блока.

  .. code-block:: delphi
    :caption: Пример использования

    <SQL>
      <GetCost>
      [Out cost]
        begin
          select price into :cost
          from table
          where code = :id;
        end;
      </GetCost>
    </SQL>

    <Pascal>
      ExecSQL('GetCost');
      value := GetVar('Cost');
      ShowMessage(IntToStr(Value * 10));
    </Pascal>


.. pas:function:: ExecSQLEx(BlockName: String; ParamNames, ParamTypes, ParamValues: Variant): Variant

  Метод выполняет PL/SQL-блок *BlockName*, объявленный в текущей операции,
  с возможностью передавать в SQL-блок дополнительные, не участвующие в
  контексте выборки параметры, а также возвращать их. Имена входящих
  параметров задаются в *ParamNames* через точку с запятой. В тексте
  SQL-запроса можно использовать не только передаваемые в *ParamNames*
  параметры, но и использовать параметры, имеющиеся в выборке. В случае
  совпадения имен параметров, будет использоваться параметр, переданный в
  вызове ``ExecSQLEx``. Возвращает массив значений параметров, указанных в
  *ParamNames*, в том порядке, в котором они перечислены в *ParamNames*. Если
  возвращаемый параметр участвует в секции [OUT] sql-запроса, то будет
  возвращено его новое значение. Если не участвует, то будет возвращено то
  значение, которое передавалось в *ParamValues*. Если входящих параметров
  нет, то можно передавать ``ParamNames = ''`` и ``ParamValues = []``. Количество
  параметров должно совпадать с количеством типов и с количеством
  значений. Все параметры являются входящими и могут являться
  возвращаемыми.

  :param String BlockName:
    Имя PL\\SQL sql-блока.

  :param Variant ParamNames:
    Имена входящих параметров, разделенные точкой с запятой.

  :param Variant ParamTypes:
    Массив типов параметров в формате: ``[тип1, тип2, …]`` Доступные константы
    типов параметров:

    - :pas:class:`~TFieldType.ftString`
    - :pas:class:`~TFieldType.ftInteger`
    - :pas:class:`~TFieldType.ftFloat`
    - :pas:class:`~TFieldType.ftDateTime`
    - :pas:class:`~TFieldType.ftOraBlob`
    - :pas:class:`~TFieldType.ftOraClob`
    - :pas:class:`~TFieldType.ftWideString`
    - :pas:class:`~TFieldType.ftWideMemo`


  :param Variant ParamValues:
    Массив значений параметров в формате: ``[значение1, значение2]``.

  :rtype: Variant

  .. code-block:: delphi
    :caption: Пример использования

    <SQL>
      <Save>
      [out sNotionReg]
        begin
          :sNotionReg := BTK_Loader.OutNotionToScriptText(:idNotion);
        end;
      </Save>
    </SQL>

    <Pascal>
    begin
      sRes := ExecSQLEx('save', 'idNotion; sNotionReg ',
        [ftInteger, ftString], [GetVar('id'), '']);
      // возвращаемое значение sNotionReg находится в sRes[1].
      // В sRes[0] находится передаваемый параметр idNotion.
      SaveToFile('', sRes[1]);
    end;
    </Pascal>


.. pas:function:: ExecSQLWithProgress(BlockName, Caption, Message, EventName: String; FinalValue: Integer): Variant

  Метод позволяет выполнять SQL-блоки, которые посылают по Pipe каналу
  сообщения о процессе выполнения. Методы открывают модальное окно с
  полосой прогресса, которое слушает Pipe канал с заданным именем, и
  запускают выполнение SQL-блока. Сообщения, приходящие с сервера должны
  содержать число в диапазоне **[0 .. FinalValue]**. По приходу
  сообщения с числом равным или больше FinalValue, диалог будет
  закрыт. Если ``FinalValue = 0``, то диалог будет закрыт при
  получении первого сообщения.

  :param String BlockName:
    Имя SQL-блока.

  :param String Caption:
    Текст заголовка окна.

  :param String Message:
    Cообщение.

  :param String EventName:
    Имя Pipe-канала.

  :param Integer FinalValue:
    Финальное значение.

  :rtype: Variant

  .. code-block:: delphi
    :caption: Пример использования

    <sql>
      <msg>
        declare
          i integer;
          j integer;
        begin
          i := 1;

          loop
            dbms_pipe.pack_message(to_char(i));
            j := dbms_pipe.send_message('TestEvent');
            i := i + 1;
            dbms_lock.sleep(1);

            if i = 11 then
              exit;
            end if;
          end loop;
        end;
      </msg>
    </sql>

    <pascal>
      ExecSQLWithProgress('msg', 'Заголовок', 'Сообщение', 'TestEvent', 10 );
    </pascal>

  .. warning:: |not_implemented|. Выполняется :pas:meth:`ExecSql`


.. pas:function:: ExecSQLExWithProgress(BlockName, ParamNames, ParamTypes, ParamValues, Caption, Message, EventName: String; FinalValue: Integer): Variant

  Методы позволяют выполнять SQL-блоки, которые посылают по Pipe каналу
  сообщения о процессе выполнения. Методы открывают модальное окно с
  полосой прогресса, которое слушает Pipe канал с заданным именем, и
  запускаю выполнение SQL-блока. Сообщения, приходящие с сервера должны
  содержать число в диапазоне **[0 .. FinalValue]**. По приходу
  сообщения с числом равным или больше FinalValue, диалог будет
  закрыт. Если ``FinalValue = 0``, то диалог будет закрыт при
  получении первого сообщения.

  :param String BlockName:
    Имя SQL-блока.

  :param String ParamNames:
    Имена входящих параметров, разделенные точкой с запятой.

  :param String ParamTypes:
    Массив типов параметров в формате: ``[тип1, тип2, …]`` Доступные константы
    типов параметров:
    - ftString
    - ftInteger
    - ftFloat
    - ftDateTime
    - ftOraBlob
    - ftOraClob

  :param String ParamValues:
    Массив значений параметров в формате: ``[значение1, значение2]`` Количество
    параметров должно совпадать с количеством типов и с количеством
    значений. Все параметры являются входными и могут являться выходными.

  :param String Caption:
    Текст заголовка окна.

  :param String Message:
    Сообщение.

  :param String EventName:
    Имя Pipe-канала.

  :param Integer FinalValue:
    Финальное значение.

  :rtype: Variant

  .. code-block:: delphi
    :caption: Пример использования

    <sql>
      <msg>
      [OUT idpValue]
        declare
          i integer;
          j integer;
        begin
          i := 1;
          :idpValue := 'Возвращаемое значение';

          loop
            dbms_pipe.pack_message(to_char(i));
            j := dbms_pipe.send_message('TestEvent');
            i := i + 1;
            dbms_lock.sleep(1);

            if i = 11 then
              exit;
            end if;

          end loop;
        end;
      </msg>
    </sql>

    <pascal>
      R :=  ExecSQLExWithProgress('msg', 'idpValue', [ftString], ['Входящее
      значение'], 'Заголовок', 'Сообщение', 'TestEvent', 10 );
      ShowMessage(R[0]);
    </pascal>

  .. warning:: |not_implemented|. Выполняется :pas:meth:`ExecSqlEx`