6. Модули сервера статистики

6.1. Краткая аннотация модулей

Эта глава явлвется справочником описаний модулей сервера статистики. Описания помещены в алфавитном порядке. Для удобства навигации можно воспользоваться главой " Струтура сервера" или краткими аннотациями, приведенными ниже.

accadmin

Позволяет администратору (или какой-либо программе-frontend'у) внести изменения в лицевой счет определенного абонента (или всех абонентов сразу).

convertstat

Читает статистику из формата `.st' и на основе указанных в пользовательской конфигурации прайс-листов преобразует ее, записывая результаты в SQL таблицу statistic.

mkreport

Генерирует отчеты на основе заранее подготовленных форм. Формы позволяют включать в себя довольно сложные операции, в том числе условное выполнение.

setrate

Позволяет задать курс валюты, вносит его в SQL таблице rates.

calcmail

Более или менее универсальный фильтр для преобразования почтовой статистики в формат `.st'.

calctime

Преобразователь статистики времени пребывания пользователей в системе в формат `.st' (на основе чтения wtmp). Смотрите также вспомогательный модуль amlast.

ckconfig

Проверяет структуру SQL-таблиц, конфигурационные файлы, наличие необходимых для работы сервера каталогов. Кроме того, этот модуль используется другими утилитами сервера для чтения конфигурации.

evaluate

Вычисляет значения заданных формул. Формулы могут включать ссылки на лицевой счет, статистическую информацию и т.п. Удобен для применения в собственных дополнениях к серверу и просто для небольших расчетов ``на ходу''.

ulist

Выводит список пользователей сервера или их домашних каталогов. Удобен для написания собственных дополнений к серверу.

htreport

Принимает и обрабатывает запросы пользователей через WWW (cgi) в интерактивном режиме.

listener

Принимает почтовые запросы от пользователей, помещает их в очередь и, если надо, запускает обработчик.

runqueue

Разбирает очередь почтовых запросов от пользователей отвечая им.

daily

Отрабатывается ежедневно (смотрите главу " Настройка/регулярные действия"). Представляет собой доступный для редактирования скрипт.

monthly

Отрабатывается один раз в месяц, первого числа. Представляет собой доступный для редактирования скрипт.

registrate

Позволяет получить исходную информацию для генерации ключа. Смотрите также главу " Установка/Регистрация".

upgrade

Позволяет более или менее безопасно мигрировать с предыдущей версии сервера статистики на текущую. Обязательно прочитайте описание!

6.2. Правила задания дат в модулях сервера статистики

Многие команды генератора отчетов включают в качестве одного или нескольких аргументов даты. Формат их задания таков:

      [дата][+|-смещение][+|-смещение]..

И дата и смещение задаются в виде трех чисел разделенных точками - года, месяца и дня (именно в таком порядке!). Любое из чисел может быть пропущено - при этом при задании даты соотвествующее поле берется из текущей даты, а при задании смещения - принимается равным нулю. При добавлении/вычитании смещения вычисления производятся независимо сначаля для года, потом для месяца и наконец дня. Результат нормализуется к соответствующей ``легальной'' дате.

Примеры (предполагается, что текущая дата - 22 июня 1996 года):

      ..1               --> 1 июня 1996 года
      +1                --> 22 июня 1997 года
      .1-1              --> 22 января 1995 года
      -..1              --> 21 июня 1996 года ("вчера")
      ..1+.1-..1        --> 30 июня 1996 года
      1980.1.1+..1000   --> 27 сентября 1982 года

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

6.3. Правила записи формул

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

Примеры формул:

2+2
(127+12)/(123-17)
(total()-statistic())*(1+taxes)
statistic(.6) ? 1000 : 0
((account()>1000 && statistic()<10000) ? 0 : 50000)*(1+taxes)

Количество уровней вложенности скобок практически неограничено.

1. Арифметические операции.

   +, -, *, /

   Сложение, вычитание, умножение и деление соответсвенно.

   x % y

   Получение остатка от деления x на y. Подразумевается, что y - целое число.

2. Логические операции. Ложь - 0, истина - не ноль. Нулем (и соответственно ложью) также считаются числа, чья абсолютная величина составляет меньше одной миллионной.

   x > y

   Истинно если x больше y.

   x < y

   Истинно если x меньше y.

   x >= y

   Истинно если x больше или равно y.

   x <= y

   Истинно если x меньше или равно y.

   x == y

   Истинно если абсолютное значение разницы x и y меньше одной миллионной.

   x != y

   Истинно если абсолютное значение разницы x и y больше или равно одной миллионной.

   x && y

   Истинно если логические выражения x и y истинны.

   x || y

   Истинно если истинно логическое выражение x или логическое выражение y.

3. Операция выбора.

   x ? y : z

   Результатом является выражение y если логическое выражение x истинно и z в противном случае. Следует отметить, что в отличие от аналогичного оператора языка C вычисляются как выражение y, так и выражение z и лишь затем происходит выбор результата.

В порядке убывания приоритета операторы располагаются так:

1. * и /
2. %
3. + и -
4. <, >, <=, >=, == и !=
5. && и ||
6. ? (оператор выбора)

Среди операторов каждой группы приоритета порядок вычисления не определен. Т.е. нельзя заранее сказать в каком порядке будет вычисляться выражение `x+y-z'.

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

Существует несколько функций, доступных при вычислени функций всегда:

1. Математические функции.

   abs(x)

   Результатом является абсолютное значение выражения x.

   max(x,y)

   Результатом является большее из двух значений выражений x и y.

   min(x,y)

   Результатом является меньшее из двух значений выражений x и y.

   round(x,[p])

   Результатом является число, полученное из значения выражения x по правилам округления. Вторым параметром может быть задана точность - положительное число, возможно дробное. По умолчанию округление происходит до целых.

   sign(x)

   Результатом является -1, если x меньше нуля; 0, если равно нулю и 1, если значение x больше нуля.

2. Функции для работы с датами.

   day(date)

   Результатом является день даты date. Здесь и далее дата записывается по стандартным правилам.

   ldate(date)

   Результатом является целое положительное число, цифры которого сформированы из даты date - ГГГГММДД (например для 9-го августа 1996 года результатом будет 19960809).

   month(date)

   Результатом является месяц даты date.

   year(date)

   Результатом является год даты date.

3. Финансовые функции и константы

   taxes

   Константа ставки налога, определенная в основном конфигурационном файле.

   vatonly(sum)

   Вычисление суммы налога для указанной величины в предположении, что налог в нее не входит.

   withvat(sum)

   Вычисление суммы с учетом налога.

Некоторые функции доступны только в контексте конкретного пользователя. Их удобно использовать в таких модулях, как mkreport, accadmin, evaluate и т.п.

account([end,[begin]])

Сумма операций на лицевом счете пользователя. Параметрами можно указать дату до которой включительно (параметр end) и дату начиная с которой (параметр begin) будет произведена выборка информации из лицевого счета абонента. По умолчанию результатом будет остаток на лицевом счете до текущей даты (включая ``сегодняшние'' операции).

statistic([end,[begin]])

Сумма статистики за текущий месяц, указанный или интервал времени. Если указан только первый параметр (end), то выводится информация за этот месяц. Если оба (begin и end) - то за интервал времени, включающий оба эти месяца. По умолчанию (если не указано ни end, ни begin) возвращает сумму статистики за текущий месяц.

total([date])

Сумма остатка на указанную или текущую дату с учетом расходов (статистики); ``баланс'' пользователя на определенный момент.

В некторых модулях могут использоваться какие-то дополнительные функции и/или константы (например значения статистики в модуле convertstat). В этом случае соответствующие описания включены в описание модулей.