На заре своей карьеры пришлось столкнуться с обслуживанием и написанием бухгалтерских программ и систем учёта. С тех пор, несмотря на то, что прошло 18 лет, стойко держалось неприятие всего, связанного с учётом и отчётами. И кто бы мог подумать, что судьба забросит меня в компанию, занимающуюся разработкой генератора отчётов. Всё моё естество тянулось (и продолжает тянуться) к системному программированию, а участие в разработке софта для генерации отчётов — наказание за грехи молодости. Собственно говоря, эта статья рассказывает о попытке «вырваться из клетки» и совместить несовместимое — системное программирование и генераторы отчётов.
Писали ли вы когда-либо документацию? А если писали, то какой стиль использовали — сухое описание протоколов или живое повествование? Я ведь почему спрашиваю, потому что в один прекрасный момент осознал, что моему проекту требуется документация. В отличие от руководства пользователя, описание протоколов — скучный и монотонный документ без аллегорий и лирических отступлений, одни лишь форматы сообщений с описанием передаваемых и возвращаемых параметров. Когда-то для подобных вещей я использовал Microsoft Word и таблицу стилей, но, как выяснилось, выдержать точный стиль при монотонном описании протоколов очень сложно. Не верите — попробуйте сами.
В какой-то момент пришла идея — почему бы для описания протоколов не использовать генератор отчётов? Во первых, не нужно покупать средства для генерации документации, во вторых — возможность самому стать пользователем продукта, разрабатываемого моим работодателем, в третьих — возможность экспорта в различные форматы, в четвёртых — реальная возможность отделить информацию от её представления.
Сказано — сделано. В качестве источника информации была взята база данных Microsoft Access. Структура базы организована следующим образом — основная информация расположена в трёх связанных таблицах:
Master таблица Protocols содержит список и описание базовых протоколов.
Detail таблица Methods содержит список методов (функций) протоколов.
Subdetail таблица Arguments содержит список параметров (аргументов) каждого метода.
В качестве генератора документации — генератор отчётов FastReport.VCL. Запускаем дизайнер отчётов, выбираем вкладку Data и создаём новое ADO соединение:
Я воспользовался встроенным в генератор отчётов помощником и получил следующую строку:
Затем к ADO соединению добавил три источника данных, связав их между собой в связку Master-Detail-Subdetail при помощи трёх SQL запросов.
Вот так выглядят запросы:
Protocols:
Methods:
Arguments:
После этого можно добавить новую страницу к отчёту и скомпоновать отчёт.
Сравнивали ли вы когда-нибудь спецификацию на «железо» от Intel и AMD? Если да, то в чью пользу? На мой взгляд, документация от Intel более удобна для восприятия и работы с ней благодаря наличию в документе множества перекрёстных ссылок и великолепному outline. Для добавления в документацию outline необходимо сказать генератору отчётов как и откуда брать информацию. Для этого у объекта бэнд (собственно на нём и отображаются данные, выбранные из базы) есть свойство OutlineText, которое можно заполнить как статическим текстом, так и из базы. Поскольку бэнды могут быть вложенными, то информация в outline получается в виде дерева где ветви соответствуют вложенности бэндов:
Самое приятное, что при экспорте генерированного документа в PDF, экспортируется и outline.
Этой статьи бы не появилось, если мне не стало чуть тесно в рамках генератора отчётов FastReport.VCL. Дело в том, что в том или ином виде я уже обыгрывал использование генератора отчётов для создания документации на различных интернет ресурсах, но вдруг ко мне пришла блажь в виде желания сделать такой же точно отчёт при помощи другого продукта — FastReport.NET. Воспользовавшись конвертором отчётов, я обнаружил, что внешний вид без малейших проблем трансформировался из отчёта формата FR.VCL в формат FR.NET. На этом радость закончилась — источники данных при конвертации потерялись. Пришлось заново (при помощи «визарда») создавать соединение к базе данных, В результате получилась такая строка:
И SQL запросы приобрели такой вид:
Как видим, запрос для протоколов не изменился. А в двух других запросах исчез оператор WHERE
и
вместо оператора WHERE необходимо в окне «Данные» выбрать меню «Действие», затем выбрать пункт меню «Новая связь» и назначить связь подчинённой таблицы с главной.
После завершения редактирования достаточно, удерживая клавишу Ctrl, нажать латинскую P или «кликнуть» мышей по значку лупы для генерации документации и предварительного просмотра полученного документа.
Не могу не сравнить FR.VCL и FR.NET. При генерации документации FR.VCL показал лучшие результаты скорости построения отчёта. В то же время FR.NET предлагает чуть большее количество форматов экспорта (например, XPS формат), чуть более современный интерфейс и некий запас fault tolerance за счёт managed кода.
Для тех, кто считает что лучше один раз попробовать самому, чем 10 раз прочитать, выкладываю в zip архиве исходную базу данных и два шаблона отчёта в формате FR3 (FR.VCL) и FRX (FR.NET). Скачать FastReport можно с официального сайта. Вам потребуется открыть отчёт в дизайнере и отредактировать в отчёте путь к базе данных — в строке соединения необходимо указать полный путь к файлу ProtocolsSpecifications.mdb. Прошу прощения за неудобство.
Напоследок хочется ещё раз обратиться к преимуществам такого метода описания протоколов и немного помечтать. Основное преимущество — разделение информации и её представления. Разработчик сосредотачивается на описании протоколов, а о внешнем виде за него заботится генератор отчётов. Возможность очень просто экспортировать документ во множество широко распространённых форматов документов.
Если MS Access заменить на какой-либо SQL сервер и предоставить пользователям через WEB интерфейс редактировать базу данных — можно производить удалённую разработку протоколов сразу несколькими разработчиками. Благо, генератор отчётов имеет серверную версию, способную генерировать отчёты на лету и отдавать их по HTTP протоколу.
Наконец, базу данных можно использовать как некий аналог IDL (Interface Definition Language). Т.е. практически ничего не мешает генерировать заголовочные файлы С/C++ с описанием интерфейсов непосредственно из базы данных.
Спасибо за внимание.
Писали ли вы когда-либо документацию? А если писали, то какой стиль использовали — сухое описание протоколов или живое повествование? Я ведь почему спрашиваю, потому что в один прекрасный момент осознал, что моему проекту требуется документация. В отличие от руководства пользователя, описание протоколов — скучный и монотонный документ без аллегорий и лирических отступлений, одни лишь форматы сообщений с описанием передаваемых и возвращаемых параметров. Когда-то для подобных вещей я использовал Microsoft Word и таблицу стилей, но, как выяснилось, выдержать точный стиль при монотонном описании протоколов очень сложно. Не верите — попробуйте сами.
В какой-то момент пришла идея — почему бы для описания протоколов не использовать генератор отчётов? Во первых, не нужно покупать средства для генерации документации, во вторых — возможность самому стать пользователем продукта, разрабатываемого моим работодателем, в третьих — возможность экспорта в различные форматы, в четвёртых — реальная возможность отделить информацию от её представления.
Сказано — сделано. В качестве источника информации была взята база данных Microsoft Access. Структура базы организована следующим образом — основная информация расположена в трёх связанных таблицах:
Master таблица Protocols содержит список и описание базовых протоколов.
Detail таблица Methods содержит список методов (функций) протоколов.
Subdetail таблица Arguments содержит список параметров (аргументов) каждого метода.
В качестве генератора документации — генератор отчётов FastReport.VCL. Запускаем дизайнер отчётов, выбираем вкладку Data и создаём новое ADO соединение:
Я воспользовался встроенным в генератор отчётов помощником и получил следующую строку:
Provider=Microsoft.Jet.OLEDB.4.0;User ID=Admin;Data Source=ProtocolsSpecifications.mdb;Mode=Share Deny None;Jet OLEDB:System database="";Jet OLEDB:Registry Path="";Jet OLEDB:Database Password="";Jet OLEDB:Engine Type=5;Jet OLEDB:Database Locking Mode=1;Jet OLEDB:Global Partial Bulk Ops=2;Jet OLEDB:Global Bulk Transactions=1;Jet OLEDB:New Database Password="";Jet OLEDB:Create System Database=False;Jet OLEDB:Encrypt Database=False;Jet OLEDB:Don't Copy Locale on Compact=False;Jet OLEDB:Compact Without Replica Repair=False;Jet OLEDB:SFP=False;
Затем к ADO соединению добавил три источника данных, связав их между собой в связку Master-Detail-Subdetail при помощи трёх SQL запросов.
Вот так выглядят запросы:
Protocols:
SELECT P.Name, P.Description, P.ProtocolID, P.Description_Rus
FROM
Protocols P
Methods:
SELECT S.ProtocolID, S.Label, S.Name, S.Description, S.Description_Rus, S.ID
FROM
Methods S
WHERE
S.ProtocolID =:ProtocolID
ORDER BY
S.Label
Arguments:
SELECT A.ID, A.InOutFlag, A.Index, A.TypedUntypedFlag, A1.Name, A.Name, A.Description
FROM
Arguments A
INNER JOIN ArgType A1 ON (A.TypedUntypedFlag=A1.ID)
WHERE
A.ID =:ID
ORDER BY A.ID , A.InOutFlag DESC, A.IndexПосле этого можно добавить новую страницу к отчёту и скомпоновать отчёт.
Сравнивали ли вы когда-нибудь спецификацию на «железо» от Intel и AMD? Если да, то в чью пользу? На мой взгляд, документация от Intel более удобна для восприятия и работы с ней благодаря наличию в документе множества перекрёстных ссылок и великолепному outline. Для добавления в документацию outline необходимо сказать генератору отчётов как и откуда брать информацию. Для этого у объекта бэнд (собственно на нём и отображаются данные, выбранные из базы) есть свойство OutlineText, которое можно заполнить как статическим текстом, так и из базы. Поскольку бэнды могут быть вложенными, то информация в outline получается в виде дерева где ветви соответствуют вложенности бэндов:
Самое приятное, что при экспорте генерированного документа в PDF, экспортируется и outline.
Этой статьи бы не появилось, если мне не стало чуть тесно в рамках генератора отчётов FastReport.VCL. Дело в том, что в том или ином виде я уже обыгрывал использование генератора отчётов для создания документации на различных интернет ресурсах, но вдруг ко мне пришла блажь в виде желания сделать такой же точно отчёт при помощи другого продукта — FastReport.NET. Воспользовавшись конвертором отчётов, я обнаружил, что внешний вид без малейших проблем трансформировался из отчёта формата FR.VCL в формат FR.NET. На этом радость закончилась — источники данных при конвертации потерялись. Пришлось заново (при помощи «визарда») создавать соединение к базе данных, В результате получилась такая строка:
Provider=Microsoft.Jet.OLEDB.4.0;Data Source=ProtocolsSpecifications.mdb;User ID=Admin
И SQL запросы приобрели такой вид:
SELECT P.Name, P.Description, P.ProtocolID, P.Description_Rus
FROM
Protocols P
Как видим, запрос для протоколов не изменился. А в двух других запросах исчез оператор WHERE
SELECT S.ProtocolID, S.Label, S.Name, S.Description, S.Description_Rus, S.ID
FROM
Methods S
ORDER BY
S.Label
и
SELECT A.ID, A.InOutFlag, A.Index, A.TypedUntypedFlag, A1.Name, A.Name, A.Description
FROM
Arguments A
INNER JOIN ArgType A1 ON (A.TypedUntypedFlag=A1.ID)
ORDER BY A.ID , A.InOutFlag DESC, A.Index
вместо оператора WHERE необходимо в окне «Данные» выбрать меню «Действие», затем выбрать пункт меню «Новая связь» и назначить связь подчинённой таблицы с главной.
После завершения редактирования достаточно, удерживая клавишу Ctrl, нажать латинскую P или «кликнуть» мышей по значку лупы для генерации документации и предварительного просмотра полученного документа.
Не могу не сравнить FR.VCL и FR.NET. При генерации документации FR.VCL показал лучшие результаты скорости построения отчёта. В то же время FR.NET предлагает чуть большее количество форматов экспорта (например, XPS формат), чуть более современный интерфейс и некий запас fault tolerance за счёт managed кода.
Для тех, кто считает что лучше один раз попробовать самому, чем 10 раз прочитать, выкладываю в zip архиве исходную базу данных и два шаблона отчёта в формате FR3 (FR.VCL) и FRX (FR.NET). Скачать FastReport можно с официального сайта. Вам потребуется открыть отчёт в дизайнере и отредактировать в отчёте путь к базе данных — в строке соединения необходимо указать полный путь к файлу ProtocolsSpecifications.mdb. Прошу прощения за неудобство.
Напоследок хочется ещё раз обратиться к преимуществам такого метода описания протоколов и немного помечтать. Основное преимущество — разделение информации и её представления. Разработчик сосредотачивается на описании протоколов, а о внешнем виде за него заботится генератор отчётов. Возможность очень просто экспортировать документ во множество широко распространённых форматов документов.
Если MS Access заменить на какой-либо SQL сервер и предоставить пользователям через WEB интерфейс редактировать базу данных — можно производить удалённую разработку протоколов сразу несколькими разработчиками. Благо, генератор отчётов имеет серверную версию, способную генерировать отчёты на лету и отдавать их по HTTP протоколу.
Наконец, базу данных можно использовать как некий аналог IDL (Interface Definition Language). Т.е. практически ничего не мешает генерировать заголовочные файлы С/C++ с описанием интерфейсов непосредственно из базы данных.
Спасибо за внимание.