Использование SoDA

SoDA является макросом для Word и отвечает за формирование отчетов в формате DOC и HTML на основе встроенных шаблонов. Инструмент позволяет пользователю формировать собственные шаблоны, основываясь на предустановленных, либо создавать произвольные с нуля (при помощи модуля Template View).

Базируясь на шаблонах, SoDA поддерживает возможность стандартизации типов документов в рамках проекта или компании. IBM/Rational SoDA может обеспечить соответствие проектной документации таким международным стандартам, как ISO, SEI CMM, IEEE, а также популярным отечественным ГОСТ 19 и ГОСТ 34.

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

Рассмотрим стандартные формы отчетов:

• Version – отчет по версии одного элемента из репозитория ClearCase. Позволяет отобразить историю изменений и атрибутов для конкретной версии;
• Vob – отчет по состоянию всех репозиториев в целом. Дает концептуальное представление об основных параметрах репозиториев, смонтированных в системе;
• Element – отчет по свойствам элемента. Выводит информацию о состоянии версий, атрибутов, меток и ответвлений для одного элемента;
• Region – отчет по всем используемым в проекте регионам. Дается информация по числу регионам, их именам и свойствам.

Стандартные отчеты, формируемые посредством SoDA, представляются крайне простыми, требующими существенных корректировок для использования в реальных проектах. Например, в стандартных отчетах отсутствует отчет по всем элементам репозитория, отчет по состоянию элементам в соответствии с именем пользователя (отчет по сотруднику)… и т.д. Относиться к стандартным шаблонам отчетов следует как к учебнику, на базе которого строятся более сложные и более информативные отчеты.

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

Использование встроенной системы отчетности с сохранением в виде Html

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

Модуль, отвечающий за отчетность, называется ClearCase Report Builder. Вызвать его можно из командной строки по имени ccreportbuilder (из директории \Rational\ClearCase\reports), либо из меню ОС. CCRB также можно вызывать из браузера ClearCase Explorer.

На рисунке 1 показан фрагмент экрана с работающим Report Builder

рис.1. Вид окна встроенной системы отчетности

Для генерации отчетов необходимо указать в браузере на необходимый элемент, для которого будет создаваться отчет (файл, вид, репозиторий) и нажать на кнопку Run Report. По введенным параметрам будет осуществлен поиск элементов и сгенерирован отчет в основном окне. Отчетные данные подлежат сохранению в виде Html файла, для последующего встраивания во внутрикорпоративный сайт.

Опишем основные типы отчетов, имеющих практическую ценность для проекта:
Elements

• Check-ins Since Date by User – отчет о версии элементов, которые были зарегистрированы в репозитории. Поиск осуществляется по имени пользователя и дате постановки под управления. Удобный отчет по получению информации о вновь введенных файлов под управление. Здесь учитывается особенность СС связанная с чувствительностью к используемому регистру (то есть, с точки зрения ClearCase ivanov и Ivanov — разные имена пользователей);
• Elements Created By User – список элементов созданных пользователем. СС сканирует репозиторий на предмет нахождения элементов, созданных конкретным пользователем;
• Elements With File Name – отчет по файлам или директориям. Поиск ведется по регулярному выражению (по маске);
• Version By Date – отчет по числу версий для каждого элемента репозитория;
• Elements With Attributes – отчет по элементам, которым присвоен определенный атрибут или атрибуты. Мы уже не раз упоминали о том, как удобно пользоваться дополнительным комментированием версий при помощи атрибутов. В предлагаемом отчете можно получить информацию о том, на каком файле находится атрибут (удобно при поиске элементов с атрибутом tested);
• Element With Branches – поиск элементов у которых есть ответвление;
• Element With Multiple Branch Level – поиск элементов с множественным ответвлением;
• Latest Version on Branch – отчет по последним версиям на указанном ответвлении;
• Versions With Label – отчет по номерам версий элементов, на которых имеется метка;
• Elements With Trigger – отчет по элементам, с установленными триггерами. Поиск осуществляется по имени триггера.

Vobs

• All Vobs – отчет по свойствам всех репозиториев

Views

• All Views – отчет по свойствам всех видов

Здесь приведен только основной набор базовых отчетов. Более подробно все описано в документации по ClearCase. Одно из преимуществ использования CCRB по сравнению со стандартной SoDA заключается в большем числе предустановленных отчетов и в том, что они являются рекурсивными (то есть, можно получить отчет по всем элементах, находящимся в поддиректориях). Второе преимущество связано с тем, что SoDA является внешним, по отношению к ClearCase, продукту, требующим дополнительного лицензирования.

CCRB формирует отчетные материалы посредством скриптов на встроенном языке программирования Perl (специальный диалект стандартного Perl версии 5.0). Это означает, что администратор проекта может добавлять новые скрипы в состав CCRB.

Для введения нового отчета в систему отчетности достаточно создать файл скрипта по определенным правилам и скопировать в директорию с остальными отчетами.

Использование CCRB позволит получать нужные отчеты по требованию пользователя. К отчетам должны иметь отношения все участники проекта, а не только руководители, поскольку отчет – есть одна из форм не только проектного контроля, но и локального контроля для каждого участника данных собственного рабочего пространства.

Использование командной строки для формирования элементарных отчетов

Командная строка насквозь пронизывает ClearCase, позволяя получать доступ к любым видам данным. И, как одно из следствий, позволяет получать различные отчеты. В интерпретаторе cleartool есть целый набор команд выводящих информацию об элементах, метаданных, версиях, истории изменения и т.д. (команды с префиксом ls).

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

cleartool lshistory main.cpp >> c:\report.txt

 или

cleartool lshistory -user admin -a -minor -since 20-mar-99.15:00 >> c:\report.txt

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

Некоторые команды cleartool предоставляют сервис форматного вывода по переключателю –fmt, что позволяет получать быстрые отчеты надлежащего качества (команды annotate, describe). Но и этого недостаточно, в силу того, что многие команды просто не умеют выводить информацию о группе файлов или директорий, то есть их функциональность ограничена одним элементом.

Для обхода данной особенности, необходимо применять специальную команду поиска find, которая восполняет недостаток отсутствия рекурсии и имеет в своем арсенале мощный язык запросов. Как вариант отчетности, допустимо использовать поиск элементов с формированием текстовых отчетов. Возможности команды find позволяют не только проводить поиск данных, удовлетворяющих заданным критериям, но и применять к каждому найденному элементу в результате поиска определенные действия – проводить обработку (для этого, как и в случае с триггерами, ClearCase формирует переменные среды, в которых находятся такие основополагающие переменные как, например, путь к найденному файлу — %CLEARCASE_PN%).

Например, для формирования отчета Elements Created By User (имеющегося в стандартном аборе) собственными силами можно воспользоваться следующей командой:

сleartool find. -element «{created_by (Ivanov)}» -exec «cleartool describe %CLEARCASE_PN%»

В примере ведется поиск элементов, созданных пользователем Ivanov. Для каждого найденного элемента Find вызовет команду describe, подставив в качестве аргумента переменную, содержащую путь до найденного элемента. Теперь остается только предусмотреть перенаправление вывода в текстовый файл и отчет готов.

Примитивность способа компенсируется его гибкостью. Но, как всегда есть одно «но», демонстрируемый способ не позволяет, формировать качественные отчеты (то есть отчеты установленного образца с применением различных стилей и форматов по образцу).

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

Использование языка скриптов для создания сложных форм отчетов

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

Средствами Perl можно создавать скрипты, формирующие Html-документы (метод основан на том, что все команды взаимодействуют с пользователем через стандартный вывод, а Perl является лучшим языком для работы с потоками данных). В скрипте применен самый простой метод получения информации об элементах, основанный на командных запросах к интерпретатору cleartool. Однако, есть более эффективный путь – использовать библиотеку автоматизации (Common Automation Library — CAL). Данный способ позволяет напрямую обращаться к функциям ядра ClearCase и требует дополнительной подготовки, поэтому на страницах книги не рассматривается. 

Применение данного способа позволит получить отчет любой сложности, оформленного по всем правилам.

К преимуществам способа следует отнести:

• гибкость – применение данного способа позволяет создавать отчеты любого вида;
• исполнение скрипта по расписанию – отчеты данного типа могут быть автоматизированы, то есть администратор может задать расписание, по которому будет запускаться скрипт и формировать отчет.

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

Опишем действия, выполняемые скриптом:

1. Просканировать все элементы репозитория.

2. Собрать статистику по элементам.

3. Выделенную статистику поместить в отдельные файлы (для сбора статистики, к каждому найденному элементу репозитории применяются команды describe, lshistory и lsvtree).

4. Подсчитать общее количество элементов.

5. подсчитать число файлов, находящихся в состоянии check-out.

6. Подсветить красным цветом наименования элементов, находящихся в состоянии check-out.

##########################################################

#Скрипт по формированию отчетов по элементам репозитория

#для выполнения скрипта необходимо создать директорию rep 

#исправить переменную $name так, чтобы она смотрела на 

#корневую директорию репозитория.

#Формат запуска скрипта: ccperl report_book.pl. 

#Результатом работы скрипта будет сформирован набор связанных

#HTML-страниц по каждому элементу.

#Скрипт подсчитывает сколько элементов всего в репозитории, собирает их 

#свойства.

#Все элементы находящиеся в состоянии Check-out подсвечиваются красным

#цветом.

###########################################################

#Определяем переменную для подсчета числа версий файлов, находящихся в #состоянии check-out.

$nuco=0;

$versions=0;

#Полный путь до корневой директории репозитория.

$name= «Z:\\Sem\\»;

#Формируем команду СС для поиска всех элементов с выводом данных

#на консоль.

#Список формируется без вывода расширенной информации о 

#элементе.

$arg2= «clt find $name -nxn -all -print»;

#Счетчик числа элементов в репозитории. Счет ведем с 1.

$objects=1;

#Формируем массив с заголовком для основного файла index.htm.

$head= «<HTML>

<HEAD>

<TITLE>Allo</TITLE>

<META http-equiv=\“Content-Type\“ content=\“text/html; charset=windows-1251\»> </HEAD> <BODY bgcolor=#f3fff>

<CENTER> <b>Perl Script REPORT</b></font></center> «;

#Формируем массив с заголовком для файлов, описывающих свойства

#элементов.

$head2=„<HTML>

<HEAD>

<TITLE>Allo</TITLE>

<META http-equiv=\“Content-Type\“ content=\“text/html; charset=windows-1251\»> </HEAD> <BODY bgcolor=#f3fff>

<CENTER> **** FILE **** </font></center> «;

#Формируем массив с окончанием файла.

$end=„</BODY></HTML>„;

#Создаем Index.htm для записи.

open (INDEX, „>Index.htm“);

#Вписываем шапку html-файла.

print INDEX $head;

#Формируем горизонтальную разделительную линию.

print INDEX „<HR>\n“;

#Формируем таблицу. Задаем тип линий и даем наименования

#колонкам.

print INDEX „<TABLE width=\“100%\“ border=2 cellspacing=3>\n“;

print INDEX „<tr>\n“;

print INDEX „<td> <b>ELEMENT</b>\n“;

print INDEX „<td> <b>VERSIONS</b>\n“;

print INDEX „<td> <b>NUM of CHECKOUTS</b>\n“;

#Исполняем команду, находящуюся в массиве. Команда open

#перехватывает вывод сна консоль.

open (FILE, „$arg2 |“);

#Обрабатываем ответ, выводимый командой.

while (<FILE>)

{

#Получаем построчно данные из потока и помещаем их в 

#стринговую переменную.

chomp;

@_ = split;

$buffer= «@_»;

#Формируем во временном стринге гиперссылку на файл

#с детальным отчетом

#по найденному сейчас элементу.

$temper= «<a href=\“.\\rep\\$objects.htm\“> $objects). $buffer </a>\n“; 

#Открываем для создания и записи файл для детального

#отчета.

open (OUT,“>.\\rep\\$objects.htm»);

#Вписываем в него заголовок.

print OUT $head2;

#Формируем линию.

print OUT «<HR>\n»;

#Увеличиваем индекс объектов.

$objects++;

#Записываем описание блока.

print OUT «<b>DESCRIBE ELEMENT</b>\n»;

print OUT «<br>\n»;

#Исполняем команду получения описания элемента, адрес

#которого был найден в предыдущих шагах (стринг – $buffer).

open (DESC, «cleartool desc -l $buffer |»);

#Получаем данные построчно.

while (<DESC>) {

chomp;

@_ = split;

#Вписываем в файл пробелы. Делаем принудительные

#отступы 

print OUT «&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp\n»; 

#Пишем в него текщую строку.

print OUT «@_ \n»;

print OUT «<br>\n»;

}

#Формируем следущий заголовок.

print OUT «<br>\n»;

print OUT «<b>VERSION TREE</b>\n»;

print OUT «<br>\n»;

#Даем команду получения дерева версий элемента.

open (DESC, «cleartool lsvtree -a $buffer |»);

#Обнуляем счетчики версий.

$versions=0; 

$nuco=0;

while (<DESC>) {

chomp;

@_ = split;

print OUT 

«&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp\n»; 

#Ставим условие. Если в строке есть

#слово CHECKEDOUT,

#значит, что данный элемент выведен в 

#данное состояние

#наша задача подсчитать число CO.

if ( «@_» =~ «CHECKEDOUT»)

{

#Увеличиваем счетчик числа СО на 1.

$nuco++;

#Делаем строку красного цвета,

#полужирной и выводим ее в файл.

print OUT «<font color=\“red\“>\n»;

print OUT «<b>\n»;

print OUT «@_ \n»;

print OUT «</b><font color=\“black\“>\n»; 

}else{

#Если условие не совпало, то 

#выводим данные без выделений. 

print OUT «@_ \n»;

}

print OUT «<br>\n»;

$versions++;

}

#Формируем последний заголовок.

print OUT «<br>\n»;

print OUT «<b>ELEMENTS HISTORY</b>\n»;

print OUT «<br>\n»;

#Даем команду.

open (DESC, «cleartool lshis -l $buffer |»);

#Получаем ответ и просто вписываем в файл.

while (<DESC>) {

chomp;

@_ = split;

print OUT «&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp\n»; 

print OUT «@_ \n»;

print OUT «<br>\n»;

}

#Продолжаем формирование таблицы для файла с индексами.

print INDEX «<tr>\n»;

#Условие: если было подсчитано, что check-out больше

#нуля, то эти строчки

#целиком подсвечиваются красным фоном (цвет символов не 

#меняем).

#В противном случае выводим в файл данные в соответствии

#со стандартными настройками.

if ($nuco>0){

print INDEX «<td bgcolor=\“red\“>\n»;

print INDEX $temper;

print INDEX «<td bgcolor=\“red\“>\n»;

print INDEX «$versions»;

print INDEX «<td bgcolor=\“red\“>\n»;

print INDEX «$nuco»;

}else{

print INDEX «<td>\n»;

print INDEX $temper;

print INDEX «<td>\n»;

print INDEX «$versions»;

print INDEX «<td>\n»; 

print INDEX «$nuco»;

}

print INDEX «</tr>\n»;

print OUT «<HR>\n»;

print OUT $end;

close (OUT);

}

print INDEX «</table> «;

print INDEX $end;

close (INDEX)

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

Для использования данного скрипта в реальном проекте необходимо лишь переопределить переменную $name и создать директорию rep, в которую будут помещаться файлы со статистикой по найденным элементам.