Общие параметры хранимых процедур в Showcase

Материал из Course Orchestra
Перейти к: навигация, поиск
Showcase

Создание решений на КУРС:Showcase

filterinfo

Фильтры в Showcase могут быть реализованы с помощью XForms и Grid. В случае фильтра XForms структура filterinfo определяется структурой самой формы. В самом простом случае в качестве фильтра передается mainInstance формы.

<schema>                                                                   
   <info>                                                                                                                              
      <name>aaa<name>
      <growth/>
      <eyescolour>Зеленый<eyescolour>
      <music>Классическая Эстрадная<music>
      <comment>fffffffffffff</comment>                                                                       
   </info>
</schema>

В случае фильтра Grid структура filterinfo имеет следующий вид:

<filter>
    <context>значение additional context для первой выделенной записи<context>
    <context>значение additional context для n-й выделенной записи<context>
</filter>


Действие по умолчанию

Для любого элемента информационной панели может быть задано действие по умолчанию, выполняющееся сразу после загрузки элемента в том случае, когда не выделен ни один активный элемент. Действие по умолчанию задается в output параметре @xxxsettings в хранимой процедуре для отрисовки элемента.

Параметры, содержащие контекст

Во все хранимые процедуры, отвечающие за отрисовку элементов инф. панели передаются 4 параметра с контекстами: @main_context, @add_context, @session_context и @filterinfo. В большинство процедур других типов также передаются некоторые их этих контекстов. По сути каждый из этих контекстов является xml. Но если @session_context и @filterinfo всегда содержат xml (или null), то @main_context и @add_context, как правило, содержат обычный текст, хотя могут содержать и xml. Возникает вопрос - как объявлять в БД соответствующие контекстам параметры. Ответ - рекомендуется их объявлять как varchar(MAX), а в случае необходимости приводить к xml. Причина - некоторые СУБД, например PostgreSQL, чувствительны к объявленному типу данных.

В MSSQL их можно объявлять и как varchar, и как xml, но для общности рекомендуется использовать varchar.

В зависимости от того, как вам удобнее к ним обращаться в коде хранимой процедуры. Showcase будет корректно работать в любом случае. В примерах в Фабрике балалаек @main_context, @add_context имеют тип varchar(MAX).

Порядок параметров в процедурах

При написании хранимых процедур ВАЖНО соблюдать порядок параметров. Эталоном является порядок параметров, объявленный в данном документе. Чтобы порядок легче было запомнить, ниже приведен типичный шаблон процедуры:

CREATE PROC 
	@main_context varchar(MAX)='',
	@add_context varchar(MAX)='',
	@filterinfo xml='',
	@session_context xml='',
	@element_Id varchar(MAX)='', -- если это элемент инф. панели
#- какие-то доп. параметры  
	@settings xml ='' output,
        @error_mes varchar(MAX) ='' output

Выдача сообщений об ошибках ввода для пользователей

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

__user_mes_xxx_src__

где xxx - код ошибки.

Это можно сделать вызовом RAISE, а можно путем создания индекса или check constraint, содержащую в своем имени данный шаблон. Информация об ошибках хранится в файле user.messages.xml в каталоге userdata. Файл имеет следующую структуру:

<messages>
<message id="test1" type="ERROR">
Ошибка
</message>
<message id="test2" type="WARNING">
Предупреждение
</message>
<message id="test3" type="INFO" caption="Заголовок" subtype="solutions/default/resources/group_icon_default.png">
Информация
</message>
</messages>

где

  • id - идентификатор сообщения,
  • type - тип сообщения,
  • caption - заголовок сообщения,
  • subtype - подтип сообщения (содержит картинку, которая будет отображаться в сообщении вместо стандартной).

Т.об. данный файл предназначен для хранения неких шаблонных ошибок, постоянно возникающих в разных ситуациях.

Возврат ошибок с помощью return и @error_mes

Альтернативный способ возврата сообщения из БД - это возврат из процедуры ненулевого кода возврата. В MSSQL это можно сделать с помощью конструкции:

RETURN @mesid

В диалекте PL(PG)/SQL, используемом в Oracle и PostgreSQL, нет подобной конструкции. Поэтому там нужно объявлять код возврата первым параметром процедуры.

Само сообщение возвращается в параметре процедуры @error_mes.

Важно: не все процедуры имеют полноценную поддержку данного механизма. Проверить это легко: наличие в списке параметров @error_mes означает полноценную поддержку.

Для чего нужен код возврата? В общем случае данный код будет выведен пользователю сразу после сообщения в формате: error_mes (return syntaxhighlight). Но если в файле user.messages.xml в userdata будет сообщение с идентификатором, совпадающим с кодом возврата, то два этих сообщения будут соединены. Соединение происходит следующим образом. Если в строке из user.messages.xml есть шаблон %s, то он заменяется сообщением из БД. Если же его нету, то сообщения сцепляются: сначала сообщение из user.messages.xml, потом - сообщение из БД. Таким образом user.messages.xml выступает хранилищем шаблонов, которые уточняются сообщениями из БД.

Важно: даже процедуры, не имеющие параметра @error_mes, могут возвращать пользователю сообщение из user.messages.xml при помощь кода возврата.

Выдача "ok"-сообщений (INFO, WARNING)

Существующий механизм возврата ошибок имел одну особенность -- даже если выдавалось сообщение с типом INFO или WARNING, логика работы программы была такой же, как если бы выдавалась ошибка -- текущее действие признавалось неудачным (например, грид не строился). Поэтому он был доработан таким образом, чтобы выдача "не ошибочных" сообщений (типа INFO, WARNING) приводило к нормальной отработке действия (например, грид успешно построился и выдалось информационное сообщение "Грид успешно построен"). Такие сообщения для краткости будем называть "ok"-сообщениями.

"ok"-сообщения выдаются с помощью return и @error_mes и для них действительны такие же правила построения как и для сообщений с типом ERROR (тип сообщения задается в файле user.messages.xml и т.д.)