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: реализация библиотеки.

ссылка на оригинал статьи https://habr.com/ru/post/540184/