Doc Technique - COBOL / Copybook Impact Analyzer V2

COBOL / Copybook Impact Analyzer V2 – Modernisation COBOL, CICS, DB2 et API Mapping

Objectif du guide

Installer, tester et exploiter cobol_copybook_impact_analyzer_v2.py, un utilitaire autonome qui analyse des programmes COBOL, copybooks, sections FILE/WORKING-STORAGE/LINKAGE, DB2, CICS, COMMAREA et produit des sorties utiles pour la modernisation API, JSON Schema, OpenAPI et dependency graph.

Télécharger l’utilitaire COBOL / Copybook Impact Analyzer V2

Le bouton principal pointe explicitement vers /static/toolbox/cobol_copybook_impact_analyzer_v2.py. Dépose ce script dans static/toolbox/ pour l’exposer depuis IDEO-Lab.

Download cobol_copybook_impact_analyzer_v2.py Django static tag

La V2 ne se limite plus à extraire quelques champs. Elle commence à traiter COBOL comme un écosystème complet : programmes, copybooks, layouts imbriqués, dépendances, DB2, CICS, fichiers, COMMAREA, champs sensibles, génération de schémas et comparaison avant/après copybook.

Inventory

Inventaire programmes, copybooks, fichiers, DB2 tables, CICS commands et dépendances.

Mapping

Extraction des champs COBOL, PIC, USAGE, OCCURS, REDEFINES et génération JSON/OpenAPI.

Impact

Scoring de risque, findings, comparison baseline et graph Mermaid des dépendances.

Ce que le moteur analyse

Domaine	Signaux analysés	Production attendue
Programme COBOL	`PROGRAM-ID`, divisions, sections, `CALL`, `PERFORM`, `GO TO`.	Inventaire programme, complexité, dépendances, appels internes/externes.
Copybook / fields	`COPY`, `01/05/10/77/88`, `PIC`, `USAGE`, `OCCURS`, `REDEFINES`.	Field mapping, estimation de taille, JSON Schema et impact structurel.
CICS	`EXEC CICS LINK`, `COMMAREA`, `LENGTH`, transaction candidates.	Mapping API candidate, dépendances CICS et surface d’exposition.
DB2	`EXEC SQL`, tables, cursors, statements, access patterns.	Références DB2, tables impactées, risques de modernisation.
Fichiers	`SELECT`, `ASSIGN`, `FD`, records, sequential/indexed files.	Inventaire I/O batch, fichiers candidats à API ou data service.
Modernisation	Champs sensibles, baseline compare, policy JSON, graph Mermaid.	Rapport de risque, cartographie et artefacts d’API draft.

Positionnement : la V2 est une base de modernisation COBOL vers API / JSON / OpenAPI / z/OS Connect, mais aussi un outil d’inventaire technique pour analyser l’impact des changements de copybook.

Téléchargement des fichiers

Cette page fournit les liens explicites vers le script Python, les samples COBOL/copybook, la policy JSON, les artefacts générés et le pack complet. Pour IDEO-Lab, les fichiers doivent être déposés sous /static/toolbox/.

Utilitaire principal

Script Python autonome, sans dépendance externe, utilisable sur un répertoire de sources COBOL/copybooks.

Download analyzer V2 Download ZIP

COBOL program

Programme sample avec DB2, CICS, COPY et logique API candidate.

Download .cbl

Request copybook

Copybook d’entrée pour génération JSON Schema / API request.

Download request

Response copybook

Copybook de sortie avec fields imbriqués et données sensibles.

Download response

Account record

Copybook record orienté fichier/compte client.

Download record

Baseline copybook

Version baseline utilisée pour comparer les changements de layout.

Download baseline

Policy JSON

Policy d’analyse : champs sensibles, patterns, règles site-specific.

Download policy

Artefacts générés utiles

JSON Schema

Schéma JSON produit depuis les champs COBOL.

Download schema

OpenAPI draft

Draft OpenAPI candidate pour exposition API.

Download OpenAPI

Mermaid graph

Graphe Mermaid des dépendances programme/copybooks/DB2/CICS.

Download graph

Arborescence static recommandée

static/
  toolbox/
    cobol_copybook_impact_analyzer_v2.py
    cobol_copybook_impact_analyzer_v2_pack.zip
    sample_cobol_v2_customer_api.cbl
    sample_cobol_v2_customer_request.cpy
    sample_cobol_v2_customer_response.cpy
    sample_cobol_v2_customer_response_baseline.cpy
    sample_cobol_v2_customer_account_record.cpy
    sample_cobol_v2_policy.json
    sample_cobol_v2_customer_schema.json
    sample_cobol_v2_openapi.json
    sample_cobol_v2_dependency_graph.mmd
    cobol_copybook_impact_analyzer_v2_guide.html

Installation de COBOL / Copybook Impact Analyzer V2

Le script est autonome. Il suffit d’une version Python moderne et d’un répertoire contenant des fichiers .cbl, .cob, .cpy ou équivalents.

1. Arborescence locale recommandée

cobol_impact_lab/
  bin/
    cobol_copybook_impact_analyzer_v2.py
  input/
    cobol_sources/
      sample_cobol_v2_customer_api.cbl
      sample_cobol_v2_customer_request.cpy
      sample_cobol_v2_customer_response.cpy
      sample_cobol_v2_customer_account_record.cpy
    baseline/
      sample_cobol_v2_customer_response_baseline.cpy
    sample_cobol_v2_policy.json
  output/
    reports/
    csv/
    json/
    schema/
    graph/

Lien direct du script à installer

Ce bouton pointe explicitement vers /static/toolbox/cobol_copybook_impact_analyzer_v2.py.

Download cobol_copybook_impact_analyzer_v2.py Django static tag

2. Installation Linux / macOS

mkdir -p cobol_impact_lab/bin cobol_impact_lab/input/cobol_sources cobol_impact_lab/input/baseline
mkdir -p cobol_impact_lab/output/reports cobol_impact_lab/output/csv cobol_impact_lab/output/json cobol_impact_lab/output/schema cobol_impact_lab/output/graph
cp cobol_copybook_impact_analyzer_v2.py cobol_impact_lab/bin/
cp sample_cobol_v2_customer_api.cbl cobol_impact_lab/input/cobol_sources/
cp sample_cobol_v2_customer_request.cpy cobol_impact_lab/input/cobol_sources/
cp sample_cobol_v2_customer_response.cpy cobol_impact_lab/input/cobol_sources/
cp sample_cobol_v2_customer_account_record.cpy cobol_impact_lab/input/cobol_sources/
cp sample_cobol_v2_customer_response_baseline.cpy cobol_impact_lab/input/baseline/
cp sample_cobol_v2_policy.json cobol_impact_lab/input/
cd cobol_impact_lab
python3 bin/cobol_copybook_impact_analyzer_v2.py input/cobol_sources --profile api

3. Installation Windows PowerShell

New-Item -ItemType Directory -Force cobol_impact_lab\bin, cobol_impact_lab\input\cobol_sources, cobol_impact_lab\input\baseline
New-Item -ItemType Directory -Force cobol_impact_lab\output\reports, cobol_impact_lab\output\csv, cobol_impact_lab\output\json, cobol_impact_lab\output\schema, cobol_impact_lab\output\graph
Copy-Item .\cobol_copybook_impact_analyzer_v2.py .\cobol_impact_lab\bin\
Copy-Item .\sample_cobol_v2_customer_api.cbl .\cobol_impact_lab\input\cobol_sources\
Copy-Item .\sample_cobol_v2_customer_request.cpy .\cobol_impact_lab\input\cobol_sources\
Copy-Item .\sample_cobol_v2_customer_response.cpy .\cobol_impact_lab\input\cobol_sources\
Copy-Item .\sample_cobol_v2_customer_account_record.cpy .\cobol_impact_lab\input\cobol_sources\
Copy-Item .\sample_cobol_v2_customer_response_baseline.cpy .\cobol_impact_lab\input\baseline\
Copy-Item .\sample_cobol_v2_policy.json .\cobol_impact_lab\input\
Set-Location .\cobol_impact_lab
python .\bin\cobol_copybook_impact_analyzer_v2.py .\input\cobol_sources --profile api

4. Test de validation

python bin/cobol_copybook_impact_analyzer_v2.py input/cobol_sources \
  --profile api \
  --custom-policy input/sample_cobol_v2_policy.json \
  --compare-with input/baseline \
  --html output/reports/sample_cobol_v2_report.html \
  --json output/json/sample_cobol_v2_analysis.json \
  --csv-fields output/csv/sample_cobol_v2_fields.csv \
  --csv-dependencies output/csv/sample_cobol_v2_dependencies.csv \
  --csv-findings output/csv/sample_cobol_v2_findings.csv \
  --csv-programs output/csv/sample_cobol_v2_programs.csv \
  --csv-copybooks output/csv/sample_cobol_v2_copybooks.csv \
  --csv-db2 output/csv/sample_cobol_v2_db2.csv \
  --csv-cics output/csv/sample_cobol_v2_cics.csv \
  --csv-files output/csv/sample_cobol_v2_files.csv \
  --csv-compare output/csv/sample_cobol_v2_compare.csv \
  --json-schema output/schema/sample_customer_schema.json \
  --openapi output/schema/sample_openapi.json \
  --mermaid output/graph/sample_dependency_graph.mmd

Résultat attendu : le sample doit détecter un programme, trois copybooks, plus de cinquante champs, des références DB2/CICS, des findings de modernisation et générer JSON Schema, OpenAPI et Mermaid graph.

Fichiers input attendus

La V2 accepte un fichier unique ou un répertoire complet. Elle est conçue pour travailler sur des sources COBOL et copybooks déjà exportés en texte depuis un repository mainframe, Git, Endevor, Changeman ou équivalent.

Utilitaire nécessaire pour analyser les sources

Télécharger d’abord le script Python, puis lancer l’analyse sur un dossier de sources COBOL/copybooks.

Download analyzer V2

1. Types de fichiers acceptés

Type	Contenu typique	Usage
`.cbl / .cob`	Programmes COBOL, divisions, procedures, EXEC SQL/CICS.	Inventaire programme, dépendances, modernisation applicative.
`.cpy`	Copybooks, layouts 01/05/10, PIC, OCCURS, REDEFINES.	Mapping field-level, JSON Schema, impact de changement.
Policy JSON	Patterns de champs sensibles, règles site-specific.	Adapter le scoring et les findings à un contexte entreprise.
Baseline folder	Ancienne version de copybooks ou programmes.	Comparer avant/après et détecter les impacts de layout.

2. Exemple minimal de copybook

01 CUSTOMER-REQUEST.
   05 REQUEST-HEADER.
      10 REQUEST-ID        PIC X(36).
      10 CHANNEL-CODE      PIC X(08).
   05 CUSTOMER-KEY.
      10 CUSTOMER-ID       PIC 9(10).
      10 CUSTOMER-SSN      PIC X(11).
   05 REQUEST-OPTIONS.
      10 INCLUDE-ACCOUNTS  PIC X(01).
      10 MAX-ROWS          PIC 9(04) COMP.

3. Samples disponibles

Customer API program

Programme COBOL avec COPY, DB2 et CICS LINK.

Download

Request copybook

Layout d’entrée pour endpoint API candidate.

Download

Response copybook

Layout de sortie avec données client et compte.

Download

Account record

Record orienté batch/file section.

Download

Response baseline

Ancienne version utilisée pour le diff.

Download

Policy JSON

Paramétrage des patterns sensibles.

Download

Règle de sécurité : un vrai copybook peut révéler des noms de champs sensibles, structures métier, tables DB2, transactions CICS et conventions internes. Utiliser une version anonymisée pour partage externe.

Utilisation quotidienne

1. Mode démo intégré

python cobol_copybook_impact_analyzer_v2.py --demo

2. Analyse simple d’un répertoire source

python cobol_copybook_impact_analyzer_v2.py input/cobol_sources --profile modernization

3. Analyse complète avec tous les exports

python cobol_copybook_impact_analyzer_v2.py input/cobol_sources \
  --profile api \
  --custom-policy input/sample_cobol_v2_policy.json \
  --compare-with input/baseline \
  --json output/json/analysis.json \
  --html output/reports/report.html \
  --csv-fields output/csv/fields.csv \
  --csv-dependencies output/csv/dependencies.csv \
  --csv-findings output/csv/findings.csv \
  --csv-programs output/csv/programs.csv \
  --csv-copybooks output/csv/copybooks.csv \
  --csv-db2 output/csv/db2.csv \
  --csv-cics output/csv/cics.csv \
  --csv-files output/csv/files.csv \
  --csv-compare output/csv/compare.csv \
  --json-schema output/schema/customer_schema.json \
  --openapi output/schema/openapi.json \
  --mermaid output/graph/dependency_graph.mmd

4. Mode batch strict

python cobol_copybook_impact_analyzer_v2.py input/cobol_sources \
  --profile production \
  --html output/reports/nightly_cobol_impact.html \
  --csv-findings output/csv/nightly_findings.csv \
  --fail-on WARNING

Lecture recommandée : commencer par le rapport HTML pour la compréhension humaine, puis utiliser les CSV/JSON pour alimenter un référentiel technique, un catalogue d’API candidates ou un dashboard de modernisation.

Paramètres de ligne de commande

1. Paramètres d’entrée et de sortie

Paramètre	Description	Exemple
`input_path`	Fichier ou répertoire COBOL/copybooks à analyser.	`input/cobol_sources`
`--profile`	Profil d’analyse : `modernization`, `api`, `db2`, `cics`, `batch`, `training`.	`--profile api`
`--custom-policy`	Policy JSON pour patterns sensibles et règles site-specific.	`--custom-policy input/policy.json`
`--compare-with`	Répertoire baseline pour comparaison avant/après.	`--compare-with input/baseline`
`--html`, `--json`	Exports principaux pour rapport humain et intégration technique.	`--html output/report.html`
`--json-schema`, `--openapi`, `--mermaid`	Artefacts de modernisation et mapping API.	`--openapi output/openapi.json`

2. Exports CSV disponibles

Paramètre	Contenu	Usage
`--csv-fields`	Champs COBOL normalisés : niveau, nom, PIC, usage, taille, parent.	Mapping field-level, analyse API, documentation.
`--csv-dependencies`	Dépendances COPY/CALL/DB2/CICS/fichiers.	Dependency graph, impact analysis.
`--csv-findings`	Anomalies, risques, recommandations.	Backlog de modernisation ou audit technique.
`--csv-programs`	Programmes détectés et métriques principales.	Inventaire applicatif.
`--csv-copybooks`	Copybooks, champs, complexité et références.	Catalogue copybook.
`--csv-db2` / `--csv-cics`	Références DB2 et CICS.	Exposition API, analyse transactionnelle.

3. Exemple profil API

python cobol_copybook_impact_analyzer_v2.py input/cobol_sources \
  --profile api \
  --json-schema output/schema/customer_schema.json \
  --openapi output/schema/customer_openapi.json \
  --mermaid output/graph/customer_graph.mmd

Exemples d’utilisation

Scénario 1 – Inventaire COBOL / copybooks

Cas de départ : obtenir une cartographie des programmes, copybooks, champs et dépendances.

python cobol_copybook_impact_analyzer_v2.py input/cobol_sources \
  --profile modernization \
  --html output/reports/inventory_report.html \
  --csv-programs output/csv/programs.csv \
  --csv-copybooks output/csv/copybooks.csv \
  --csv-dependencies output/csv/dependencies.csv

Scénario 2 – Génération JSON Schema / OpenAPI

Cas modernisation : préparer un endpoint API candidat à partir d’un layout COBOL.

python cobol_copybook_impact_analyzer_v2.py input/cobol_sources \
  --profile api \
  --json-schema output/schema/customer_schema.json \
  --openapi output/schema/customer_api_openapi.json \
  --html output/reports/api_candidate_report.html

Scénario 3 – Impact avant/après modification copybook

Cas critique : comparer une nouvelle version avec une baseline avant mise en production.

python cobol_copybook_impact_analyzer_v2.py input/cobol_sources \
  --compare-with input/baseline \
  --csv-compare output/csv/copybook_compare.csv \
  --html output/reports/copybook_impact_report.html

Scénario 4 – Analyse DB2 / CICS

Cas transactionnel : extraire les tables DB2 et commandes CICS pour évaluer les dépendances runtime.

python cobol_copybook_impact_analyzer_v2.py input/cobol_sources \
  --profile cics \
  --csv-db2 output/csv/db2_references.csv \
  --csv-cics output/csv/cics_references.csv \
  --mermaid output/graph/runtime_dependencies.mmd

Scénario 5 – Contrôle nocturne automatisé

0 4 * * * /opt/cobol-impact/bin/python /opt/cobol-impact/cobol_copybook_impact_analyzer_v2.py \
  /data/cobol/source/current \
  --profile production \
  --compare-with /data/cobol/source/baseline \
  --html /var/www/reports/cobol/nightly_impact.html \
  --csv-findings /var/log/cobol/nightly_findings.csv \
  --json /var/log/cobol/nightly_analysis.json \
  --fail-on WARNING >> /var/log/cobol/cobol_impact.log 2>&1

Modernisation API, JSON Schema et OpenAPI

Le rôle le plus stratégique de cette V2 est de transformer des assets COBOL en artefacts compréhensibles par les équipes modernes : JSON Schema, OpenAPI, graph de dépendances et catalogue de champs.

1. Chaîne de transformation recommandée

COBOL source + copybooks
  -> field extraction
  -> dependency inventory
  -> sensitive field detection
  -> JSON Schema draft
  -> OpenAPI draft
  -> human validation
  -> API gateway / zOS Connect candidate

2. Artefacts de sortie

Artefact	Contenu	Usage
JSON Schema	Types JSON dérivés de PIC, groupes, OCCURS et formats numériques.	Contrat de données, validation payload, mapping front/back.
OpenAPI draft	Endpoint candidat, request/response schema, metadata API.	Point de départ pour design API et z/OS Connect.
Mermaid graph	Relations entre programmes, copybooks, DB2 tables, CICS commands.	Documentation visuelle, impact analysis, onboarding.
Field CSV	Mapping détaillé des champs COBOL.	Review métier, mapping data, conformité, anonymisation.

3. Points à valider manuellement

Les REDEFINES ne se convertissent jamais automatiquement sans arbitrage métier.
Les OCCURS DEPENDING ON doivent être validés avec les règles de cardinalité réelle.
Les champs COMP-3 nécessitent une validation du signe, de l’échelle et des décimales.
Les copybooks partagés peuvent impacter plusieurs programmes et plusieurs endpoints candidats.
Les champs sensibles doivent être classés avant exposition API.

Attention : l’outil génère un draft technique, pas un contrat API final. Les artefacts doivent être relus par un expert COBOL, un architecte API et un responsable sécurité/data.

Exports et exploitation des résultats

Rapport HTML

Vue lisible : score, findings, programmes, copybooks, DB2, CICS, fields et dépendances.

Analyse JSON

Format complet pour API, ingestion SQL, archivage ou comparaison automatique.

Fields CSV

Une ligne par champ COBOL avec PIC, usage, niveau, taille et parent.

Dependencies CSV

Dépendances COPY, CALL, DB2, CICS, fichiers et graph technique.

JSON Schema / OpenAPI

Artefacts de modernisation pour API candidate.

Mermaid

Graph visuel exploitable dans documentation Markdown ou portail technique.

Exemple de synthèse console

COBOL / Copybook Impact Analyzer V2
Status           : HIGH_RISK
Highest severity : WARNING
Risk score       : 100/100
Files            : 4
Programs         : 1
Copybooks        : 3
Fields           : 51
Dependencies     : 9
DB2 references   : 1
CICS references  : 1
Findings         : 22

Idée de table SQL pour historisation

CREATE TABLE cobol_impact_run (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    source_name VARCHAR(255),
    profile VARCHAR(32),
    status VARCHAR(32),
    highest_severity VARCHAR(16),
    risk_score INTEGER,
    program_count INTEGER,
    copybook_count INTEGER,
    field_count INTEGER,
    db2_reference_count INTEGER,
    cics_reference_count INTEGER,
    finding_count INTEGER,
    report_path VARCHAR(500),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Vision produit : la V2 peut devenir un véritable référentiel d’assets COBOL : inventory, impact analysis, API candidates, data contracts, dependency graph et score de modernisation.

Dépannage et bonnes pratiques

1. Le script ne détecte pas de champs

Cause possible	Correction
Le fichier n’est pas en texte brut.	Exporter les sources COBOL/copybooks en texte ASCII/UTF-8 ou EBCDIC converti.
Les colonnes COBOL ont été modifiées.	Conserver la structure source, éviter les conversions qui cassent les niveaux et PIC.
Copybooks manquants.	Ajouter les répertoires de copybooks au dossier d’analyse.
Syntaxe site-specific.	Ajouter progressivement des règles parser ou une policy adaptée.

2. Les JSON Schema semblent incomplets

Certains layouts COBOL ne sont pas convertibles automatiquement : REDEFINES, OCCURS DEPENDING ON, champs signés, packed decimal, layouts multi-records et zones conditionnelles. Le schéma généré est un draft de travail.

python cobol_copybook_impact_analyzer_v2.py input/cobol_sources \
  --profile api \
  --custom-policy input/sample_cobol_v2_policy.json \
  --json-schema output/schema/review_schema.json \
  --csv-fields output/csv/review_fields.csv

3. Check-list avant partage externe

Anonymiser les noms de programmes, copybooks, tables DB2, transactions CICS et champs sensibles.
Vérifier les champs type SSN, CARD, ACCOUNT, BALANCE, SECURITY, CUSTOMER, EMPLOYEE.
Ne jamais exposer directement un copybook de production sans validation sécurité.
Relire les artefacts OpenAPI avant diffusion : l’outil produit un draft, pas un contrat final.
Conserver une baseline pour mesurer les impacts de changement.

Point critique : les copybooks sont des contrats de données métier. Une mauvaise conversion ou exposition API peut introduire des erreurs de données, de sécurité ou de compatibilité applicative.