Enterprise COBOL: пример проекта
Эта статья завершает Курс программирования на COBOL, освещая важные аспекты разработки программного обеспечения, такие как модульность кодовой базы, зависимости, модульное тестирование, мокинг, DevOps на z/OS и автодокументация. Современный подход представлен здесь наилучшим образом — на примере.
TLDR
Скачайте архив с GitHub, разархивируйте от откройте папку sales
.
Предварительные условия
Предполагается, что вы уже знакомы с основными принципами, методами и стандартами IBM Enterprise COBOL для z/OS — проприетарного компилятора COBOL, который реализует значительную часть стандартов COBOL 85, COBOL 2002 и COBOL 2014. Мы будем запускать проект на z/OS — проприетарной 64-разрядной операционной системе для мэйнфреймов IBM, которая вышла в октябре 2000 года и все еще обратно совместима с функциями, появившимися с 1960-х годов.
Убедитесь, что у вас установлен NPM, менеджер пакетов для JavaScript:
$ npm -v
У вас есть аккаунт мэйнфрейма IBM.
Вы можете получить аккаунт в учебных целях бесплатно. Зарегистрируйтесь в IBM и следуйте инструкциям. Вы получите емейл с указанным USER ID, IP и PORT. Затем войдите в Open Mainframe Project Slack и добавьте приложение zih через Apps меню. Отправьте приложению сообщение, например, Hi, и бот попросит ввести емейл и USER ID, которые вы получили. Отправьте эти данные, и бот создаст ваш PASSWORD.
Вам понадобится COBOLget, менеджер пакетов для COBOL:
$ npm i -g cobolget
$ cobolget -v
Вам понадобится Zowe, платформа управления для мэйнфреймов с открытым исходным кодом, и ваш профиль Zowe, созданный с использованием указанных выше данных:
$ npm i -g @zowe/cli --ignore-scripts
$ zowe -V
$ zowe profiles create zosmf ztrial --host <IP> --port <PORT> --user <USER ID> --pass <PASSWORD> --reject-unauthorized false
Profile created successfully!
Вы можете выбрать любой текстовый редактор по вашему желанию, но я рекомендую Visual Studio Code с установленным расширением IBM Z Open Editor.
Спецификация
У хороших проектов есть исчерпывающее описание функциональности и ограничений. Наш проект Sales суммирует вымышленные продажи в определенном регионе. Данные о продажах представлены в формате CSV, где каждая строка (кроме заголовка) описывает одну продажу следующим образом:
Region,Country,Units Sold,Unit Price,Total Revenue
Region и Country это PIC X(48)
, Units Sold это PIC 9(9)
, Unit Price и Total Revenue это PIC 9(9)V99
монетарные десятичные значения. Желаемый регион также PIC X(48)
. Для простоты мы определим фильтр по региону прямо в основной программе, и будем полагать, что строки CSV не могут превышать 80 символов.
Декомпозиция
Благодаря Zowe программисты COBOL могут создавать любую структуру проекта, свободную от условностей и ограничений мэйнфреймов. Современная разработка имеет тенденцию фокусироваться на проблемной области, делегируя специфичные для платформы задачи на уровень DevOps.
Разберем спецификацию на функциональные блоки. В основном программа:
Читает файл продаж.
Разбирает строки одну за другой.
Проверяет Region на соответствие.
Агрегирует Total Revenue.
Отображает агрегированное значение.
Таким образом, можно выделить как минимум четыре блока — три программы и одну copybook. Точка входа определяет фильтр по региону, вызывает Reader и отображает результат. Программа Reader инкапсулирует операции с файлами (DataSet) и анализирует записи CSV, возвращаемые Parser. Программа Parser преобразует строки CSV в записи.
├── src
├── parser.cbl
├── reader.cbl
├── sales.cbl
└── sales.cpy
Другими словами, наша copybook — это структурированная форма строки CSV, совместно используемая в Reader и Parser. Поместим ее в файл CPY:
01 csv-rec.
05 Region PIC X(48).
05 Country PIC X(48).
05 UnitsSold PIC 9(9).
05 UnitPrice PIC 9(9)V99.
05 TotalRevenue PIC 9(9)V99.
Зависимости
До того, как Zowe разделил среду разработки и исполнения, инженеры Enterprise COBOL использовали следующие блоки комментариев для документирования изменений:
*****************************************************************
* DATE CHANGED BY DESCRIPTION *
* -------- ------------ -------------------------------------*
* 99.99.99 Author Description *
Этот метод не вполне отражает историю программы и не может использоваться для ретроспективного анализа. Напротив, Системы Контроля Версий в настоящее время являются стандартом в разработке программного обеспечения, позволяя командам сотрудничать через пространство, время и границы организаций. Эксперименты с кодом, параллельные версии, атомарные модификации и обзоры кода помогают разрабатывать софт эффективно с низким уровнем риска.
Тенденция разделения монолитных программ с огромным количеством SECTIONS на более мелкие и многократно используемые блоки была бы невозможна без Семантического Версионирования и Управления Пакетами. Несмотря на то, что в наших модулях мы не использовали никакой внешний код, встроенных в COBOL функций (Intrinsic functions) обычно недостаточно в более сложных проектах.
С 2020 года у COBOL есть собственный менеджер пакетов COBOLget, который стандартизирует повторное использования исходного кода разработчиками как открытого, так и проприетарного кода. Инструмент командной строки автоматизирует процесс установки и обновления библиотек, разрешения зависимостей и интеграции внешнего кода COBOL в проекты. Реестр COBOLget аккумулирует библиотеки на диалектах GnuCOBOL и Enterprise COBOL, помогая доставлять публичный и закрытый код командам.
Сердце COBOLget — это Манифест modules.json, который описывает проект и его зависимости.
...
"modules": [
"src/parser.cbl",
"src/reader.cbl",
"src/sales.cbl"
],
"dialect": "entcobol",
"dependencies-debug": {
"ecblunit": "*"
}
...
Как видно, структура очень похожа на манифест в NPM. В свойствах modules
перечислены COBOL-модули проекта, свойство dialect
определяет целевую платформу. Назначение зависимости ecblunit
будет объяснено в следующей главе.
Тестирование
Хорошие проекты обеспечивают разумную степень гарантии качества - каждый модуль должен работать как задумано. В нашем проекте Reader и Parser - это два модуля, которые мы можем изолировать от среды и покрыть тестами на самой ранней стадии разработки.
├── tests
├── tests.cbl
└── tests.jcl
Инструменты
Для этого IBM предлагает проприетарную среду модульного тестирования — zUnit. zUnit реализует стандарт xUnit, позволяющий разрабатывать, выполнять и оценивать результаты тестов на любом языке z/OS. Конвейер выглядит так:
Test Runner читает файл Test Suite;
Test Runner по очереди вызывает Test Cases;
ADDTESTS
добавляет тестовые программы в Test Case;SETUP
выделяет необходимые ресурсы;тестовая программа вызывает модуль и проверяет результат;
TEARDOWN
высвобождает выделенные ресурсы.
Test Runner — программа z/OS, которая управляет процессом тестирования.
Test Suite — XML-файл, в котором перечислены Test Cases для Test Runner.
Test Case — COBOL программа, вызывающая модуль.
Assertion — COBOL условие, сравнивающее ожидаемые и фактические значения.
Test Fixture — COBOL программы для настройки, запуска и завершения тестов.
Проблема в том, что для одного минимального теста zUnit требуется более 100 строк типового кода, что в простых случаях применения чрезмерно. К счастью, имеется альтернатива с открытым исходным кодом — ECBLUnit. В отличие от zUnit, этот инструмент ориентирован только на элементы Test Runner и Assertion. Написанный на Enterprise COBOL, инструмент полностью совместим с z/OS. Тесты ECBLUnit — это программы на COBOL, намного более простые, чем тесты zUnit. Поскольку ECBLUnit это обычный пакет COBOLget, мы можем добавить его как зависимость:
$ cobolget add --debug ecblunit
$ cobolget update
$ cobolget install
Мокинг
Кажется, в нашем проекте полностью изолированным элементом является только Parser. Reader требует поддержки z/OS для доступа к CSV-файлу. Тем не менее, мы можем изолировать Reader, создав его alter ego — Мок. Цель имитации — сосредоточиться на тестируемом коде, а не на поведении или состоянии его окружения. Мок реализует контракт исходного модуля с поддельной реализацией:
IDENTIFICATION DIVISION.
PROGRAM-ID. READER.
DATA DIVISION.
WORKING-STORAGE SECTION.
COPY SALES.
01 csv-row PIC X(48) VALUE 'Europe,Germany,10,9.99,99.90'.
LINKAGE SECTION.
01 where PIC X(48).
01 total PIC 9(9)V99 VALUE 0.
PROCEDURE DIVISION USING where RETURNING total.
CALL "PARSER" USING csv-row RETURNING csv-rec.
MOVE TotalRevenue to total.
END PROGRAM READER.
Поскольку в процессе тестирования JCL компилирует мок сразу после настоящих модулей, тестовая программа не замечает подмены.
...
01 expected-total PIC 9(9)V99 VALUE 99.90.
...
CALL "READER" USING where RETURNING total.
CALL "ECBLUREQ" USING
BY CONTENT ADDRESS OF expected-total
BY CONTENT ADDRESS OF total
BY CONTENT LENGTH OF expected-total.
Этот простой подход позволяет тестировать бизнес-логику любой сложности, избегая нежелательных зависимостей. Давайте теперь соберем и протестируем наши модули на z/OS:
$ cobolget run build
...
Modules modules.cpy and modules.cbl updated.
$ cobolget run test
...
OK
Tests: 001, Skipped: 000
Assertions: 002, Failures: 000, Exceptions: 000
DevOps
Не отчаивайтесь, если приведенная выше команда не сработала. В scripts
манифеста вы найдете все необходимые сценарии для согласования сред разработки и выполнения. Вы можете запускать эти команды отдельно или в группах, указав начальное имя сценария. Замените все <USER-ID>
в скриптах на свой и попробуйте создать датасеты мэйнфрейма разом:
$ cobolget run setup
Если датасет уже существует, команда завершится ошибкой. Тогда придется создать датасеты по одному, например:
$ cobolget run setup:RES
Если все прошло успешно, то теперь можно развернуть и запустить проект Sales на z/OS:
$ cobolget run build
$ cobolget run p
...
Total: 0033368932.11
Сценарии сборки, развертывания, тестирования и демонстрации запущены и работают. Отлично!
CI
Проект следует практике Непрерывной Интеграции, где каждая модификация кода тестируется в репозитории. Среди файлов проекта вы можете найти два шаблона:
nodejs.yml — для GitHub
.gitlab-ci.yml — для GitLab
Оба шаблона повторяют шаги, описанные выше, и имеют похожий синтаксис. GitLab и GitHub будут запускать CI процессы автоматически и сообщать о прогрессе во вкладках Pipelines и Actions соответственно. Ненулевой код выхода на любом этапе пометит процесс как сбойный.
Если вы решите опубликовать проект в своем репозитории, не забудьте объявить переменные HOST, PORT, USER и PASS в Settings->CI/CD->Variables в GitLab или в Settings->Actions secrets в GitHub.
Документация
Программисты постоянно читают код. Обычно соотношение времени, потраченного на чтение и на запись, намного превышает 10:1. Говорящие названия переменных, разделов, абзацев, множество комментариев объясняют читателю, что происходит и почему. IBM рекомендует использовать IDENTIFICATION DIVISION для описания программ. Вот фрагмент, вставляемый IBM Z Open Editor:
*****************************************************************
IDENTIFICATION DIVISION.
PROGRAM-ID. MYPROG.
AUTHOR. MYNAME.
INSTALLATION. COBOL DEVELOPMENT CENTER.
DATE-WRITTEN. 01/01/08.
DATE-COMPILED. 01/01/08.
SECURITY. NON-CONFIDENTIAL.
*****************************************************************
С точки зрения модульности, такая документация не предоставляет исчерпывающую информацию о контракте модуля без необходимости его тщательного изучения. Поэтому вендоры COBOL добавили в комментарии дополнительные теги, распознаваемые генераторами автодокументации. Внедрение автоматического документирования сокращает объем вмешательства, необходимого для его поддержки, снижает затраты и улучшает качество, делая отражение изменений в кодовой базе более эффективным.
В 2020 году Bruno Pacheco выпустил инструмент с открытым исходным кодом, который генерирует документацию из исходного кода COBOL — coboldoc. Инструмент решает проблему несовместимости стандартов документации между диалектами COBOL. Coboldoc распознает теги Microfocus, MSDN и Free Format и может создавать документацию в форматах HTML и Markdown.
*>**
*> Detailed description.
*> @summary <text> short description.
*> @author <text> defines the author(s).
*> @license <text> defines the license.
*> @param <type> <name> defines the input
*> @return <type> Defines the outout.
*>**
Имея некоторый опыт работы с последователями Javadoc, вы найдете данный фрагмент очевидным. Теперь установим Coboldoc и сгенерируем документацию для модулей:
$ npm i -g coboldoc
$ coboldoc -v
$ coboldoc generate src/*.cbl -o coboldoc
Заключение
60-летний язык программирования по-прежнему актуален. По оценкам Micro Focus, COBOL используется в 70% глобальных систем обработки транзакций, на нем написаны 220 миллиардов строк кода. Надеюсь, что аспекты, освещенные в этой статье, вдохновят вас на дальнейшее развитие экосистемы. Спасибо за чтение!
Вы энтузиаст COBOL? Давайте разрабатывать недостающие библиотеки вместе — читайте далее Enterprise COBOL: реализация библиотеки.