<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
          "DTD/xhtml1-transitional.dtd">

<html>

<head>
  <title>DbReader</title>
  <meta http-equiv="Content-Type" content="text/html; charset=koi8-r" />
</head>

<body>
<h1>DbReader</h1>

<h2>Установка программы</h2>
<ol>
<li>Распаковать архив.</li>

<li>Установить источник данных:<br />
в Windows 2000: Панель управления/Администрирование/Источники данных (ODBC), добавить biotopes-data.mdb.</li>

<li>Настроить программу:<br />
В файле dbreader.properties указать имя, присвоенное источнику данных:<br />
    <code>resource: jdbc:odbc:<em>имя</em></code><br />
и путь к каталогу, относительно которого программа будет искать изображения (содержащий biotopephotos и maps):<br />
    <code>resource_base: C:\\biotopes</code><br />
(символ '\' необходимо дублировать)</li>

<li>Запуск программы:<br />
<code>dbreader.bat</code> или<br />
<code>java -jar dbreader.jar</code>.<br />
Для запуска необходима Java Runtime Environment (JRE) 5.0, можно скачать с <a href="http://java.sun.com/j2se/1.5.0/download.jsp">http://java.sun.com/j2se/1.5.0/download.jsp</a>. Возможно, будет работать и со старыми версиями JRE - не проверял.

Все значения файла конфигурации можно переопределять при запуске программы:<br />
команда <code>java -Dru.karrc.dbreader.<em>ключ</em>=<em>значение</em> -jar dbreader.jar</code><br />
(например: <code>java -Dru.karrc.dbreader.log=dbreader.log -jar dbreader.jar</code>)</li>
</ol>

<h2>Работа программы</h2>

<p>Программа выполняет запрос biotope.sql (или другой, указанный в dbreader.properties), после чего обрабатывает файл biotope.template, заменяя найденные в нем инструкции на результаты их выполнения.</p>
<p>Формат инструкций: <code><%<em>список_функций</em>[:|\]<em>данные</em>%></code>, <em>список функций</em> - имена функций разделенные пробелом, список может быть пустым. Если указано несколько функций, они выполняются начиная с последней.</p>

<h3>Разделители между списком функций и данными</h3>

<ul>
  <li><code>:</code> - данные будут обрабатываться рекурсивно.</li>
  <li><code>\</code> - данные будут переданы функции без обработки. Можно использовать для экранирования комбинаций символов <code><%</code> и <code>%></code> (<code><%\<%%></code> и <code><%\%%>></code>).</li>
</ul>

<h3>Функции</h3>

<ul>
  <li><code><%get:<em>имя</em>%></code><br />
  Заменяется на значение встроенной переменной или колонки запроса.</li>

  <li><code><%optional:<em>текст</em>%></code><br />
  Заменяется на <em>текст</em>, если в нем найдены инструкции, заменившиеся на непустые строки, иначе заменяется на пустую строку.</li>

  <li><code><%escape:<em>текст</em>%></code><br />
  Заменяет в тексте "опасные" символы (таблица замен задается в файле конфигурации).</li>

  <li><code><%invoke:<em>имя</em>; <em>парам1</em> <em>парам2</em> ... <em>парамN</em>%></code><br />
  Выполняет запрос с параметрами <em>имя</em>.sql и заменяется на результаты обработки шаблона <em>имя</em>.template. Значения параметров подставляются в запрос вместо символа '?'.</li>

  <li><code><%image:<em>исх_файл</em> <em>кон_файл</em> <em>формат</em> [<em>макс_ширина</em>] [<em>макс_высота</em>]%></code><br />
  Загружает изображение из файла <em>исх_файл</em> (путь определяется относительно конфигурационного параметра "resource_base") и преобразует его в указанный формат, сохраняя результат в <em>кон_файл</em>. Если заданы максимальная высота и ширина, большие изображения будут уменьшены.
При успешном выполнении, инструкция <code><%image:...%></code> будет заменена на значение <em>кон_файл</em>, иначе - на пустую строку.</li>

  <li><code><%copy:<em>исх_файл</em> <em>кон_файл</em>%></code><br />
  Копирует файл <em>исх_файл</em> (путь определяется относительно конфигурационного параметра "resource_base") в <em>кон_файл</em>. При успешном выполнении, инструкция <code><%copy:...%></code> будет заменена на значение <em>кон_файл</em>, иначе - на пустую строку.</li>
</ul>

<h3>Встроенные переменные</h3>

<p><code>NUMBER</code> - порядковый номер строки результата выполнения запроса.
Чтобы обратиться к переменной запроса, из которого обрабатываемый шаблон был вызван с помощью функции invoke, перед именем переменной нужно добавить <code>SUPER.</code> (например: <code>SUPER.NUMBER</code>).</p>

<h3>Пример</h3>

<p>Следующая инструкция получит значение из столбца name и заменит в нем специальные символы:</p>
<p><code><%escape get:name%></code></p>

<p align="right"><i><a href="mailto:kryshen@cs.karelia.ru">Михаил Крышень</a></i></p>

</body>
</html>