![[Назад]](rprev.gif)
![[Дальше]](rnext.gif)
![[Оглавление]](rtoc.gif)
mkreport [-m] [-n] [-ofile] [-S subj] [-I] [-c] [-O] [-T today]
-uuser|-a -ttotal:form | form_source
Генератор отчетов читает форму и преобразовывает ее в соответствии с заданными в ней командами. В результате может быть получено практически что угодно - от PostScript файла с факсом для счета до .html файла со списком пользователей. Фактически, даже результаты почтовых запросов пользователя к серверу статистики (смотрите модуль runqueue) преобразуются в формы и передаются генератору отчетов.
Форма может быть прочитана из стандартного входного потока (в этом случае
необходимо задать `-' в качестве ее имени), или из файла. В случае
указания входного файла его первым символом может быть `~' (тильда)
- в этом случае форма будет прочитана из домашнего каталога пользователя,
или символ `=' (знак равенства) - при этом поиск формы сначала производится
в домашнем каталоге пользователя, а затем в подкаталоге `forms/'
домашнего каталога сервера. Последнее удобно для переопределения форм
по умолчанию для некоторых пользователей.
Кроме того, для того, чтобы позволить иметь разные формы на разных
языках, в первую очередь происходит попытка открыть файл с именем, в
котором перед последней точкой вставлено `.XX' (где XX - код
языка). Если соответствующий файл не найден, то производится попытка
открыть файл для системного языка, и, наконец, если и он не найден, то
открывается файл как он задан.
Таким образом, если для пользователя `user' установлен язык `ru', а
системный язык - `en', и задано имя формы `=form.fm', то попытки
открытия файлов будут вестись в следующей последовательности:
`.../userbase/u/user/form.ru.fm' (в домашнем каталоге)`.../forms/form.ru.fm'`.../userbase/u/user/form.en.fm'`.../forms/form.en.fm'`.../userbase/u/user/form.fm'`.../forms/form.fm'По умолчанию результаты обработки форм выводятся в стандартный выходной
поток, однако можно вывести его в файл задав ключ
`-o'
. Как
обычно, если имя файла начинается с тильды, то файл выводится в
персональный каталог пользователя. Кроме того, при этом реально
размещение файла происходит в каталог, соответствующий текущему году -
например в каталог `1998/' для 1998 года. Это позволяет не
загромождать каталог пользователя ``лишними'' файлами, так как доступ к
отчетам бывает необходим довольно редко.
Часто бывает необходимо разослать результаты обработки форм пользователям - для этого можно применить ключ `-m' . В этом случае результаты обработки будут отправлены по почте на адрес, заданный параметром `postmaster' в файле настроек пользователя. Тема письма по умолчанию (``** Сообщение сервера статистики'') может быть изменена ключом `-S' .
Для обработки формы для одного пользователя его идентификатор должен быть задан в ключе `-u' , если же необходимо по одной форме расчитать всех пользователей, то следует использовать ключ `-a' . По умолчанию, из обработки исключаются пользователи, имеющие статус ``закрыт''. Чтобы обойти это ограничение можно использовать ключ `-n' . Вывести отчеты долько для пользователей не имеющих статуса `Nonofficial' можно задав ключ `-O' .
Если для всех операторов формы не требуются никакие пользовательские данные, то ключ `-u' можно не указывать.
Для рассылки предупреждений удобно использовать ключ `-t' . Его аргумент состоит из двух частей, разделенных двоеточием - числового значения и имени формы, которую следует использовать, если баланс пользователя меньше или равен этому значению. Допустимо использовать несколько ключей `-t' в одной строке.
Иногда бывает полезно сымитировать вывод отчета `задним числом' - для этого можно установить текущую дату ключом `-T' . Формат задания даты стандартен. При этом из обработки автоматически исключаются пользователи, которых не существовало к моменту, указанному ключом `-T' (проверка производится по параметру whowhen персональных настроек пользователя). Для того, чтобы обойти это ограничение можно использовать ключ `-c' , хотя трудно представить ситуацию, когда это может понадобиться.
Форма - это простой текстовый файл, который посимвольно копируется в отчет за исключением специальных команд, которые заключаются в символы `<>' (если иного не задано параметром конфигурации report-delimiters). Если необходимо вставить в текст символ `<' (или иные специальные символы) его необходимо ``защитить'' вставкой перед ним символа `\' (backslash). Чтобы вставить в текст символ `\' его необходимо удвоить. Кроме того, в формах допустимы комментарии - начало комментария выделяется парой символов `/*', а конец - парой `*/'.
Команда состоит из ключевого слова (регистр символов игнорируется) и нескольких необязательных аргументов, отделенных от ключевого слова и друг от друга некоторым количеством пробелов и/или табуляций. Аргументы состоят из имени аргумента и необязательного значения аргумента разделенных знаком равенства. Между именем аргумента и знаком равенства и между знаком равенства и значением аргумента пробелы недопуспустимы.
При необходимости вставить пробел или символ `>' в значение аргумента, символ может быть ``защищен'' с помощью backslash - `\' или все значение аргумента может быть взято в двойные кавычки. Для включения символа кавычки в значение аргумента он также должен быть ``защищен'' символом `\'.
Если символ `\' является самым последним символом в строке, то перевод строки игнорируется (не выводится в выходной поток).
Пример формы:
На <date value="..1"> остаток на Вашем лицевом счете \ составляет <total> <currency>. (<total bywords>) Статистика оказанных Вам услуг за период с <date value="..1-.1"> \ по <date value="..1-..1">: <stattable begin="-.1" end="-.1" withvat> |
Результатом может быть примерно такой текст:
На 22.06.1996 остаток на Вашем лицевом счете составляет 1'692'255 руб. (Один миллион шестьсот девяносто две тысячи двести пятьдесят пять руб.) Статистика оказанных Вам услуг за период с 1.05.1996 по 31.05.1996: ======================== Статьи расхода за 8/1995 ======================== Комментарий Единица Кол-во Цена Итого -------------------------------------------------------------------------- ----------------------------- Почтовые услуги ---------------------------- Бесплатная почта кбайт 19.25 0.00 0 Внутрирегиональная почта кбайт 34.32 4.51 135 Внутрироссийская почта кбайт 3.72 90.12 315 Международная почта кбайт 0.75 270.35 180 --------------------- Повременно оплачиваемые услуги --------------------- Dialup TCP/IP (работа в мин 2181.10 180.23 393'089 Internet) -------------------------------------------------------------------------- Итого: 393'720 НДС 20%, руб.: 78'744 Итого с учетом НДС, руб.: 472'464 ========================================================================== |
Ниже в алфавитном порядке перечислены все все ключевые слова (команды), распознаваемые в формах и возможные модификаторы. Допустимо сокращать названия команд и модификаторов до необходимого для однозначной идентификации числа знаков.
Вывод лицевого счета абонента. Если не указано никаких модификаторов, то выводит последние 10 операций на лицевом счете табличкой шириной в 79 символов без НДС. Пример вывода:
============================ Лицевой счет ============================
Дата Приход Расход Остаток Комментарий
----------------------------------------------------------------------
17.04.1996 -12'958 301'792 Списание НДС
17.04.1996 -64'791 237'001 Списание НДС
01.05.1996 -106'704 130'297 Услуги за 4/1996
01.06.1996 -477'383 -347'086 Услуги за 5/1996
11.06.1996 500'000 152'914 rate=5020
11.06.1996 -83'333 69'581 Списание НДС
01.07.1996 -1'585'040 -1'515'459 Услуги за 6/1996
19.07.1996 3'760'774 2'245'315 П/п 001 от 18.07
19.07.1996 -626'796 1'618'519 Списание НДС
01.08.1996 -932'739 685'780 Услуги за 7/1996
======================================================================
|
Возможные модификаторы:
Задает дату, начиная с которой должен выводиться счет. По умолчанию - с самого начала, насколько позволяет количество выводимых строк.
Задает вывод суммы остатка лицевого счета ``словами''.
Вывод счета будет прекращен на этой дате (включительно). По умолчанию - ограничения нет.
Задает заголовок, который будет выведен в первой строке таблицы.
Задает сколько последних строк (операций) лицевого счета будет выведено. Если лицевой счет содержит меньше операций, то выводится сколько есть. По умолчанию - 10 строк.
Задает точность вывода денежных величин. По умолчанию используется точность, принятая в системе для национальной валюты или значение параметра currency-precision конфигурации сервера.
Если задан этот флаг, то выводится только итоговая сумма - остаток на лицевом счете.
Задает смещение от левой границы при выводе информации ``словами''. Используется для правильного переноса по словам. По умолчанию - 0.
Задает ширину вывода - как для табличного вывода, так и для вывода словами. Значение по умолчанию - 79.
Если задан этот флаг, то в случае вывода лицевого счета ``табличкой'' к таблице приписываются строки с итоговым значением остатка, НДС и остатка вместе с НДС. Если флагами total или bywords задан вывод только остатка, то выводится остаток вместе с НДС.
Вывод текущей или заданной даты; псевдоним для команды date.
Отличается только тем, что значеним формата по умолчанию является
`"%e" %B %Y', дающий даты в виде `"8" августа 1996'.
Вывод номера договора пользователя, заданного директивой contract в его конфигурационном файле. Эквивалентно команде `print extension=contract'.
Вывод наименования основной валюты сервера.
Вывод текущей или заданной даты в указанном формате. Если никаких
модификаторов не указано, то выводит текущую дату в виде
DD.MM.YYYY (например 8.10.1996 для 8 августа 1996 года).
Возможные модификаторы:
Позволяет задать формат вывода даты. Содержимое заданной строки посимвольно копируется в вывод, за исключением специальных последовательностей, которые начинаются с символа `%' (знак процента), за которым следует одно- или двухбуквенный код формата. Для того, чтобы вставить в формат символ процента его необходимо удвоить. Допустимые коды форматов:
Если задан этот флаг, то вывод даты происходит с помощью функции C strftime (смотрите `strftime (3)').
Задает дату, подлежащую выводу. Формат записи даты стандартен (смотрите описание выше).
Вывод домена, определенного параметром domain конфигурации пользователя. Эквивалентно команде `print extension=domain'.
Не имеет самостоятельного значения и используется только как часть условного блока, задаваемого командой if, означающая ``иначе''. Допустимо внутри одного блока if иметь несколько операторов else - каждый будет менять зачение флага ``выполнять/не выполнять'' на противоположное.
Используется как закрывающий элемент для условного блока, задаваемого командой if.
Условное выполнение. Модификатором value должно быть задано выражение. В случае его истинности (значение не равно нулю) выполняются следующие за командой if до команды fi или else операторы. Допустимы вложенные условные блоки. Смотрите также описания команд else и fi.
Пример:
<if value="2*2 == 4">\ Дважды два равно четыре, проверено электроникой. <else>\ О-о-о.. Для вас - 2*2=<print value=2*2> <fi>\ |
Добавление обратного слеша после операторов if, else, fi является рекомендуемой практикой - позволяет улучшить читаемость формы без выдачи ``лишнего'' перевода строки в выходной поток.
Включение в выходной поток указанной формы или файла. На имена файлов распространяются те-же правила именования, что и на имена форм в аргументах к модулю mkreport (смотрите выше). Команда не имеет смысла без одного из модификаторов:
Включает указанный файл в выходной поток. Никаких действий над файлом не производится, он вставляется как есть. Полезно для включения разного рода готовых вставок созданных другими программами.
Включает результаты обработки указанной формы генератором отчетов. Очень удобно для включения каких-то стандартных форм в часто меняющиеся (например счета на доплату).
Псевдоним команды print, отличается только тем, что по умолчанию использует модификатор `symbol="="'.
Вывод физического адреса абонента, определяемого параметрами addrr и addre его конфигурационного файла. В зависимости от модификатора выводится название на национальном языке (native) или на английском (english). Пример формы:
Адрес на национальном языке: <location native> Адрес на английском языке: <location english> |
Вывод названия организации абонента на национальном языке (модификатор native или по умолчанию) или на английском (модификатор english). Смотрите параметры orgr и orge конфигурации пользователя. Эквивалентно команде `print extension=organization'.
Вывод телефонов, по которым можно связаться с абонентом так, как они были заданы параметром phones в конфигурации пользователя. Эквивалентно команде `print extension=phones'.
Вывод электронного почтового адреса администратора пользователя так, как он был задан параметром postmaster в его конфигурации. Эквивалентно команде `print extension=postmaster'.
Вывод разнообразных значений, расчеты по формулам. Не имеет смысла без хотя-бы одного из модификаторов:
Выводит вычисленное значение ``словами''.
Задает значение по умолчанию для модификатора extension.
Указывает на пожелание выдать дополнительную информацию (extension) на английском языке. Если в конфигурации пользователя она не определена, то выводится значение default.
Выводит указанный дополнительный параметр из конфигурации пользователя в соответствии с заданным форматом. Могут быть также заданы модификаторы native и english, указывающие соответственно на пожелание выдать информацию на местном или английском языках. По умолчанию выводится параметр на `родном' языке, если он задан, и на английском, если нет.
Задает формат вывода значения. Формат посимвольно копируется в выходной поток за исключением нескольких спецификаторов, начинающихся с символа `%' (знак процента). Для того, чтобы встваить в формат знак процента его необходимо удвоить. Возможные спецификаторы (их более подробное описание можно увидеть в любой документации на библиотеки языка C - `printf(3)'):
Указывает на пожелание выдать дополнительную информацию (extension) на родном языке. Если в конфигурации пользователя она не определена, то выводится значение default.
Задает точность, до которой будет округлено вычисленное значение. По умолчанию используется точность, принятая в системе для национальной валюты или значение параметра currency-precision конфигурации сервера.
Задает смещение от левой границы при выводе информации ``словами''. Используется для правильного переноса по словам. По умолчанию - 0.
Если задан этот параметр или параметр width, то подразумевается, что вывод строки командой print будет произведен внутри ``линейки'' из указанных символов. При этом первый символ формата рассматривается как указатель способа расположения строки в линейке: `<' - сдвинуто влево, `=' - по центру, `>' - сдвинуто вправо.
Задает выражение, значение которого подлежит выводу (подробнее о формулах и допустимых в них функциях и операторах смотрите выше.
Если указан этот флаг, то выводится значение налога, вычисленное из value по формуле `round(round(value)*(1+taxes)-round(value))'. Гарантируется, что выведенное по такой форме выражение будет истинным:
<print val="..." withvat> == <print val="..."> +
<print val="..." vatonly>
|
Задает ширину выводимой линейки. По умолчанию - 79 символов.
Если задан этот флаг, то к значению value добавляется налог.
Вывод имени представителя абонента на национальном языке (модификатор native или по умолчанию) или на английском (модификатор english). Смотрите параметры namer и namee конфигурации пользователя. Эквивалентно команде `print extension=realname'.
Вывод адреса администратора сервера статистики так, как он задан параметром admin основного конфигурационного файла. Удобно использовать в таком контексте:
.. замечания и предложения можно высказать администратору сервера по адресу <statadmin>. ... |
Вывод статистики расходов пользователя. По умолчанию выводит статистику табличкой за последний месяц. Пример вывода по умолчанию:
====================== Статьи расхода за 8/1996 ====================== Комментарий Единица Количество Цена Итого ---------------------------------------------------------------------- __________________________ Почтовые услуги ___________________________ Международная кбайт 13.38 155.91 2'087 почта Внутрироссийская кбайт 1820.70 51.97 94'622 почта Бесплатная почта кбайт 7.67 0.00 0 ___________________ Повременно оплачиваемые услуги ___________________ Dialup TCP/IP мин 354.27 207.88 73'645 (работа в Internet) ________________ Прочие коммерческие почтовые системы ________________ Получение кбайт 5.69 187.09 1'065 информации от системы RELIS ---------------------------------------------------------------------- Итого: 171'419 ====================================================================== |
Возможны модификаторы:
Альтернативный способ вывода таблички (по просьбе Sergey Ganichev <sergey@comcent.nikolaev.ua). При этом способе вывода налоги включаются в каждую строку и после всей таблицы выдается итоговое значение:
====================== Статьи расхода за 8/1996 ====================== Комментарий Единица Количество Цена Итого ---------------------------------------------------------------------- __________________________ Почтовые услуги ___________________________ Международная кбайт 13.38 187.09 2'504 почта Внутрироссийская кбайт 1820.70 62.36 113'546 почта Бесплатная почта кбайт 7.67 0.00 0 ___________________ Повременно оплачиваемые услуги ___________________ Dialup TCP/IP мин 354.27 249.46 88'374 (работа в Internet) ________________ Прочие коммерческие почтовые системы ________________ Получение кбайт 5.69 224.51 1'278 информации от системы RELIS ---------------------------------------------------------------------- Итого: 205'702 В том числе НДС: 34'284 ====================================================================== |
Дата, начиная с которой будет выводиться статистика. Имеют значение только месяц и год. По умолчанию - текущая.
Дата, до которой (включительно) вудет выводиться статистика. Имеют значение только месяц и год. По умолчанию - текущая.
Задает заголовок, который будет выведен в первой строке таблицы статистики. По умолчанию - ``Статистика за месяц/год''.
Выводит таблицу в формате HTML 3.0 с некоторыми расширениями Netscape. Если Вам хочется иметь доступ к статистике (смотрите описание модуля htreport) из Lynx или иного несовместимого с последними стандартами браузера, то лучше использовать конструкцию, подобную такой:
\<pre\> <statistic withvat> \</pre\> |
Задает ширину таблицы. По умолчанию - 79 символов.
Если задан этот флаг, то под таблицей приводится итоговое значение с НДС и значение НДС:
... ________________ Прочие коммерческие почтовые системы ________________ Получение кбайт 5.69 187.09 1'065 информации от системы RELIS ---------------------------------------------------------------------- Итого: 171'419 НДС: 34'284 Итого с НДС: 205'703 ====================================================================== |
Вывод итогового значения остатка с учетом расходов. Вычисляется как разница остатка на лицевом счете на текущую (или указанную) дату и суммы расходов за месяц. Возможны модификаторы:
Вывод суммы ``словами''.
Задает дату на которую должен быть посчитан остаток. Формат даты стандартен. По умолчанию - текущая дата.
Задает точность вывода. По умолчанию используется точность, принятая в системе для национальной валюты или значение параметра currency-precision конфигурации сервера.
Задает смещение от левой границы при выводе информации ``словами''. Используется для правильного переноса по словам. По умолчанию - 0.
Задает ширину при выводе словами. По умолчанию - 79 символов.
Если задан этот флаг, то в сумму итогового остатка включается НДС.
Вывод внутреннего имени пользователя, его идентификатора.
Вывод названия операционной системы и типа компьютера пользователя так, как они заданы параметром system конфигурации пользователя. Эквивалентно команде `print extension=system'.
Вывод текущей версии сервера статистики вместе с ``Copyright'' и адресом автора. Если указан модификатор short, то выводится только номер версии и ничего иного.
Выод информации о том, кто и когда зарегистрировал данного пользователя на основе данных, заданных параметром whowhen конфигурации пользователя. Эквивалентно команде `print extension=whowhen'.
В качестве примеров форм смотрите поставляемые с сервером в каталоге
`forms/'. В большинстве случаев бывает удобно не писать форму
с нуля, а взять готовую и исправить ее.
Если Вам удалось создать удобную на Ваш взгляд форму и Вам хочется поделиться ей с другими - пришлите ее автору для включения в дистрибутив и/или распространения по списку рассылки.