Doc Technique - JCL Doctor V2

JCL Doctor V2 – Linter / Analyzer professionnel de JCL MVS / zOS

Objectif du guide

Installer, tester et exploiter jcl_doctor_v2.py, un utilitaire autonome qui analyse un JCL avant exécution ou après incident : syntaxe, JOB/EXEC/DD, datasets, DISP, SPACE, SORT, sécurité, restart strategy, PROC/INCLUDE et risques opérationnels.

Télécharger l’utilitaire JCL Doctor V2

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

Download jcl_doctor_v2.py Django static tag

JCL Doctor V2 est conçu comme un contrôle qualité avant lancement batch ou comme outil d’audit après incident. Il transforme un listing JCL en findings exploitables, avec score de risque, catégories, DD statements, datasets, steps, comparaison avec une baseline et exports HTML/JSON/CSV.

Lint

Contrôle des cartes JOB, EXEC, DD, PROC, INCLUDE, JCLLIB, IF/ELSE/ENDIF et paramètres critiques.

Risk

Détection des DISP dangereux, datasets sensibles, SPACE incohérents, TIME=NOLIMIT, REGION=0M et SORT incomplet.

Export

Production HTML, JSON, CSV findings, steps, DD statements, datasets, catégories et règles exportables.

Ce que le moteur analyse

Domaine	Contrôles réalisés	Diagnostic produit
Syntaxe JCL	`JOB`, `EXEC`, `DD`, `PROC`, `INCLUDE`, `JCLLIB`, continuations.	Structure du job, steps, procédures appelées, includes, cohérence globale.
DD statements	`DSN`, `DISP`, `SPACE`, `UNIT`, `DCB`, `SYSOUT`, `DUMMY`.	Allocations manquantes, suppression dangereuse, DD incomplet ou risqué.
Datasets	GDG, datasets temporaires, production-like DSN, patterns sensibles, banned patterns.	Risque sécurité, conformité naming, dataset critique ou suppression potentielle.
Restart	`RESTART=`, granularité des steps, présence d’une stratégie de relance.	Préparation production insuffisante ou relance difficile après incident.
Performance	`SORT`, `SORTWK`, `SYSIN`, `TIME`, `REGION`, allocations faibles.	Risque de job long, abend espace, SORT mal préparé, surconsommation mémoire.
Gouvernance	Commentaires, profils `production`/`security`/`strict`, policy JSON, diff baseline.	Score par catégorie, go/no-go opérationnel, contrôle avant mise en production.

Positionnement : JCL Doctor V2 sert à sécuriser les mises en production batch, aider les jeunes mainframers, auditer les JCL historiques et détecter les patterns dangereux avant qu’ils ne provoquent un incident.

Téléchargement des fichiers

Cette page fournit les liens explicites vers le script Python, les samples, le catalogue de règles, le fichier de policy 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, à lancer sur un fichier JCL texte.

Download jcl_doctor_v2.py Static tag

Sample Payroll

JCL volontairement risqué : DISP DELETE, datasets sensibles, SPACE faible, TIME=NOLIMIT.

Download payroll

Sample Clean

Baseline plus saine pour comparaison avant/après ou démonstration de diff.

Download clean

Sample PROC / INCLUDE

Cas PROC, JCLLIB, INCLUDE et contrôle de structure avancée.

Download proc

Sample Security

Cas datasets sensibles, patterns sécurité, policy custom et profil security.

Download security

Rules catalog

Catalogue JSON des règles intégrées, exportable et documentable.

Download rules

Pack ZIP

Script, samples, policy, exports et rapports de démonstration.

Download ZIP

Arborescence static recommandée

static/
  toolbox/
    jcl_doctor_v2.py
    jcl_doctor_v2_pack.zip
    jcl_doctor_v2_rules_catalog.json
    sample_jcl_v2_policy.json
    sample_jcl_v2_payroll.jcl
    sample_jcl_v2_clean.jcl
    sample_jcl_v2_proc.jcl
    sample_jcl_v2_security.jcl
    jcl_doctor_v2_guide.html

Contrôle visuel : le bouton Download jcl_doctor_v2.py est présent en haut de la page, dans l’onglet Téléchargement, dans Installation et dans Fichiers input.

Installation de JCL Doctor V2

Le script est autonome. Il suffit d’une version Python moderne et d’un fichier JCL texte. Il peut être utilisé sur un poste Windows, Linux, macOS ou sur un serveur d’audit batch.

1. Arborescence locale recommandée

jcl_doctor_lab/
  bin/
    jcl_doctor_v2.py
  input/
    sample_jcl_v2_payroll.jcl
    sample_jcl_v2_clean.jcl
    sample_jcl_v2_proc.jcl
    sample_jcl_v2_security.jcl
    sample_jcl_v2_policy.json
  output/
    reports/
    csv/
    json/

Lien direct du script à installer

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

Download jcl_doctor_v2.py Django static tag

2. Installation Linux / macOS

mkdir -p jcl_doctor_lab/bin jcl_doctor_lab/input jcl_doctor_lab/output/reports jcl_doctor_lab/output/csv jcl_doctor_lab/output/json
cp jcl_doctor_v2.py jcl_doctor_lab/bin/
cp sample_jcl_v2_*.jcl jcl_doctor_lab/input/
cp sample_jcl_v2_policy.json jcl_doctor_lab/input/
cd jcl_doctor_lab
python3 bin/jcl_doctor_v2.py --demo payroll

3. Installation Windows PowerShell

New-Item -ItemType Directory -Force jcl_doctor_lab\bin, jcl_doctor_lab\input, jcl_doctor_lab\output\reports, jcl_doctor_lab\output\csv, jcl_doctor_lab\output\json
Copy-Item .\jcl_doctor_v2.py .\jcl_doctor_lab\bin\
Copy-Item .\sample_jcl_v2_*.jcl .\jcl_doctor_lab\input\
Copy-Item .\sample_jcl_v2_policy.json .\jcl_doctor_lab\input\
Set-Location .\jcl_doctor_lab
python .\bin\jcl_doctor_v2.py --demo payroll

4. Test de validation

python bin/jcl_doctor_v2.py input/sample_jcl_v2_payroll.jcl \
  --profile production \
  --compare-with input/sample_jcl_v2_clean.jcl \
  --html output/reports/sample_jcl_v2_payroll_report.html \
  --json output/json/sample_jcl_v2_payroll_analysis.json \
  --csv-findings output/csv/sample_jcl_v2_payroll_findings.csv \
  --csv-steps output/csv/sample_jcl_v2_payroll_steps.csv \
  --csv-dds output/csv/sample_jcl_v2_payroll_dds.csv \
  --csv-datasets output/csv/sample_jcl_v2_payroll_datasets.csv \
  --csv-categories output/csv/sample_jcl_v2_payroll_categories.csv

Résultat attendu : le sample payroll doit produire un rapport HTML avec un score de risque élevé, des findings sur DISP/DELETE, datasets sensibles, restart strategy, TIME/REGION et allocations.

Fichiers input attendus

JCL Doctor V2 attend un fichier texte brut contenant un job JCL. L’extension peut être .jcl, .txt, .proc, .cntl ou équivalent. Le point clé est de conserver les cartes JCL et les espaces de continuation.

Utilitaire nécessaire pour analyser les inputs

Télécharger d’abord le script Python, puis lancer l’analyse sur un fichier JCL.

Download jcl_doctor_v2.py

1. Sources acceptées

Source	Contenu typique	Usage
`JOB JCL`	Carte JOB, steps EXEC, DD statements, datasets.	Audit complet avant exécution ou mise en production.
`PROC`	Procédures cataloguées ou inline, paramètres symboliques.	Contrôle de réutilisabilité et structure batch.
`INCLUDE`	Membres inclus, JCLLIB, standard site.	Identification des dépendances et standards d’exploitation.
`Security JCL`	Datasets RACF, HR, PAYROLL, PROD, SECURITY, DELETE.	Audit sécurité et contrôle de patterns sensibles.
`Baseline JCL`	Version saine ou précédente du job.	Comparaison avec `--compare-with`.

2. Exemple minimal de JCL

//PAYROLL1 JOB (ACCT),'PAYROLL NIGHTLY',CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID
//STEP010  EXEC PGM=IEFBR14,TIME=NOLIMIT,REGION=0M
//SYSUT1   DD DSN=PAYROLL.PROD.INPUT,DISP=OLD
//SYSUT2   DD DSN=PAYROLL.PROD.OUTPUT,DISP=(OLD,DELETE)
//STEP020  EXEC PGM=SORT
//SORTIN   DD DSN=PAYROLL.PROD.INPUT,DISP=SHR
//SORTOUT  DD DSN=PAYROLL.PROD.SORTED,DISP=(NEW,CATLG,DELETE),SPACE=(TRK,(1,1))
//SYSIN    DD *
  SORT FIELDS=(1,10,CH,A)
/*

3. Samples disponibles

Payroll risk

Cas à risques pour valider les règles production.

Download

Clean baseline

JCL plus propre pour comparer les findings.

Download

PROC / INCLUDE

Contrôle des procédures et includes.

Download

Security

Cas orienté datasets sensibles et policy JSON.

Download

Règle de sécurité : un vrai JCL peut révéler datasets, applications, noms de jobs, classes JES, conventions de nommage, volumes, bibliothèques STEPLIB/JOBLIB et standards internes. Utiliser --redact avant partage externe.

Utilisation quotidienne

1. Modes démo intégrés

python jcl_doctor_v2.py --demo payroll
python jcl_doctor_v2.py --demo clean
python jcl_doctor_v2.py --demo proc
python jcl_doctor_v2.py --demo security

2. Analyse simple d’un JCL

python jcl_doctor_v2.py input/sample_jcl_v2_payroll.jcl

3. Analyse complète avec exports

python jcl_doctor_v2.py input/sample_jcl_v2_payroll.jcl \
  --profile production \
  --json output/json/payroll_analysis.json \
  --html output/reports/payroll_report.html \
  --csv-findings output/csv/payroll_findings.csv \
  --csv-steps output/csv/payroll_steps.csv \
  --csv-dds output/csv/payroll_dds.csv \
  --csv-datasets output/csv/payroll_datasets.csv \
  --csv-categories output/csv/payroll_categories.csv

4. Comparaison avec une baseline

Le paramètre --compare-with permet de comparer un JCL courant avec une version précédente ou une version propre.

python jcl_doctor_v2.py input/sample_jcl_v2_payroll.jcl \
  --compare-with input/sample_jcl_v2_clean.jcl \
  --html output/reports/payroll_vs_clean.html

5. Mode anonymisé

python jcl_doctor_v2.py input/production_job.jcl \
  --redact \
  --html output/reports/production_job_redacted.html \
  --json output/json/production_job_redacted.json

6. Mode batch strict

python jcl_doctor_v2.py input/nightly_job.jcl \
  --profile strict \
  --html output/reports/nightly_job_report.html \
  --csv-findings output/csv/nightly_job_findings.csv \
  --fail-on ERROR

Lecture recommandée : ouvrir d’abord le rapport HTML, puis utiliser les CSV pour revue technique, ticket, base SQL, dashboard ou contrôle automatique dans une chaîne de mise en production.

Paramètres de ligne de commande

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

Paramètre	Description	Exemple
`input_file`	Fichier JCL texte à analyser.	`input/job.jcl`
`--demo`	Lance un sample intégré : `payroll`, `clean`, `proc`, `security`.	`--demo payroll`
`--write-sample-jcl`	Écrit un sample intégré dans un fichier.	`--sample-name payroll --write-sample-jcl sample.jcl`
`--write-all-samples`	Écrit tous les samples intégrés dans un dossier.	`--write-all-samples samples/`
`--json`	Exporte l’analyse complète en JSON.	`--json output/analysis.json`
`--html`	Génère le rapport HTML.	`--html output/report.html`
`--csv-findings`	Exporte les anomalies détectées.	`--csv-findings output/findings.csv`
`--csv-steps`	Exporte les steps EXEC détectés.	`--csv-steps output/steps.csv`
`--csv-dds`	Exporte les DD statements détectés.	`--csv-dds output/dds.csv`
`--csv-datasets`	Exporte les datasets et attributs extraits.	`--csv-datasets output/datasets.csv`
`--csv-categories`	Exporte le score par catégorie de risque.	`--csv-categories output/categories.csv`

2. Paramètres d’analyse et de gouvernance

Paramètre	Effet	Usage recommandé
`--profile`	Profil : `production`, `batch`, `security`, `performance`, `training`, `strict`.	Ajuster la sévérité et le focus de l’analyse.
`--custom-policy`	Charge un fichier JSON avec patterns sensibles ou interdits.	Adapter aux standards d’une entreprise.
`--compare-with`	Compare avec un JCL baseline.	Revue avant/après modification.
`--export-rules`	Exporte le catalogue de règles intégré.	Documentation, audit, future table SQL.
`--redact`	Masque les noms de datasets dans les sorties.	Partage externe ou support.
`--fail-on`	Retourne un code erreur à partir d’une sévérité donnée.	`--fail-on ERROR` ou `--fail-on CRITICAL`.
`--max-findings-console`	Limite le nombre de findings affichés en console.	Réduire le bruit en batch.

3. Exemple profil sécurité avec policy custom

python jcl_doctor_v2.py input/sample_jcl_v2_security.jcl \
  --profile security \
  --custom-policy input/sample_jcl_v2_policy.json \
  --html output/reports/security_jcl_report.html \
  --csv-findings output/csv/security_jcl_findings.csv

Exemples d’utilisation

Scénario 1 – Audit pré-production d’un JCL payroll

Cas classique : vérifier un JCL critique avant mise en production.

python jcl_doctor_v2.py input/sample_jcl_v2_payroll.jcl \
  --profile production \
  --html output/reports/payroll_preprod_report.html \
  --csv-findings output/csv/payroll_preprod_findings.csv

Scénario 2 – Audit sécurité

Détecter datasets sensibles, patterns interdits et opérations destructives.

python jcl_doctor_v2.py input/sample_jcl_v2_security.jcl \
  --profile security \
  --custom-policy input/sample_jcl_v2_policy.json \
  --redact \
  --html output/reports/security_jcl_redacted.html

Scénario 3 – Analyse PROC / INCLUDE

Contrôler la structure et les dépendances d’un JCL utilisant PROC, INCLUDE et JCLLIB.

python jcl_doctor_v2.py input/sample_jcl_v2_proc.jcl \
  --profile batch \
  --html output/reports/proc_analysis.html \
  --csv-steps output/csv/proc_steps.csv \
  --csv-dds output/csv/proc_dds.csv

Scénario 4 – Comparaison avant/après modification

Comparer une version modifiée avec une baseline saine.

python jcl_doctor_v2.py input/new_job_version.jcl \
  --compare-with input/old_job_version.jcl \
  --profile production \
  --html output/reports/jcl_diff_report.html \
  --json output/json/jcl_diff_analysis.json

Scénario 5 – Contrôle nocturne automatisé

0 5 * * * /opt/jcl-doctor/bin/python /opt/jcl-doctor/jcl_doctor_v2.py \
  /data/jcl/nightly_job.jcl \
  --profile strict \
  --html /var/www/reports/jcl/nightly_job_report.html \
  --csv-findings /var/log/jcl-doctor/nightly_job_findings.csv \
  --json /var/log/jcl-doctor/nightly_job_analysis.json \
  --fail-on ERROR >> /var/log/jcl-doctor/jcl_doctor.log 2>&1

Rules catalog – Lecture des contrôles intégrés

JCL Doctor V2 embarque un catalogue de règles exportable. Il couvre les risques de structure, sécurité, allocation, performance, restart, exploitabilité et comparaison baseline.

Télécharger le catalogue de règles JCL Doctor V2

Fichier JSON utile pour documentation, audit, enrichissement manuel ou intégration dans une base SQL.

Download rules catalog

Famille	Exemples de règles	Objectif
Safety	`DISP=(OLD,DELETE)`, `DELETE` sur dataset sensible, DD incomplet.	Bloquer les suppressions ou écrasements dangereux.
Allocation	`NEW` sans `SPACE`, SPACE trop faible, absence de SMS classes.	Éviter B37/D37/E37 et allocations fragiles.
Performance	SORT sans `SORTWK`, `TIME=NOLIMIT`, `REGION=0M`.	Réduire les risques batch et consommation excessive.
Security	Patterns `PROD`, `RACF`, `SECURITY`, `PAYROLL`, policy custom.	Surveiller les datasets sensibles et opérations à risque.
Maintainability	Commentaires faibles, noms peu clairs, absence de restart strategy.	Améliorer exploitation et support production.
Structure	PROC/INCLUDE/JCLLIB, IF/ENDIF, mélange `COND` et `IF`.	Rendre le JCL plus lisible et maîtrisable.

Exporter le catalogue intégré

python jcl_doctor_v2.py --export-rules output/json/jcl_doctor_v2_rules_catalog.json

Exemple de policy JSON custom

{
  "sensitive_patterns": ["PAYROLL", "HR", "RACF", "SECURITY", "PROD"],
  "banned_patterns": ["DISP=(OLD,DELETE)", "TIME=NOLIMIT", "REGION=0M"]
}

Important : une policy custom permet d’adapter JCL Doctor aux conventions d’une entreprise : préfixes datasets, bibliothèques interdites, classes JES, standards SPACE/SMS, conventions sécurité ou règles DevOps.

Exports et exploitation des résultats

Rapport HTML

Vue lisible : score, findings, catégories, steps, DD, datasets, recommandations et diff baseline.

Analyse JSON

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

Findings CSV

Une ligne par anomalie, avec sévérité, catégorie, règle et recommandation.

Steps CSV

Une ligne par step EXEC, programme, paramètres et contexte.

DD / Datasets CSV

DD statements, DSN, DISP, SPACE, UNIT, DCB, SYSOUT, DUMMY et attributs extraits.

Categories CSV

Score par famille de risque : safety, security, allocation, performance, restart, maintainability.

Exemple de synthèse console

JCL Doctor V2
Status           : BLOCKED
Highest severity : CRITICAL
Risk score       : 100/100
Steps            : 3
DD statements    : 13
Datasets         : 6
Findings         : 16
Categories       : safety, security, allocation, performance, restart

Idée de table SQL pour historisation

CREATE TABLE jcl_doctor_run (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    source_name VARCHAR(255),
    profile VARCHAR(32),
    status VARCHAR(32),
    highest_severity VARCHAR(16),
    risk_score INTEGER,
    step_count INTEGER,
    dd_count INTEGER,
    dataset_count INTEGER,
    finding_count INTEGER,
    report_path VARCHAR(500),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Vision produit : JCL Doctor V2 peut devenir un vrai gate de mise en production batch : historique SQL, revue DevOps, audit sécurité, score de risque, comparaison baseline et décision GO/NO GO.

Dépannage et bonnes pratiques

1. Le script ne détecte pas correctement les steps ou DD

Cause possible	Correction
Le fichier n’est pas un texte brut.	Exporter le JCL en texte, pas en PDF image ou Word.
Les continuations JCL ont été cassées.	Conserver les colonnes et éviter les copier/coller qui suppriment les espaces.
Le JCL utilise des standards site spécifiques.	Ajouter une policy custom ou enrichir le catalogue de règles.
Les PROC/INCLUDE ne sont pas résolus.	Fournir le JCL expandé ou analyser séparément les membres PROC/INCLUDE.

2. Trop de findings remontées

Commencer avec le profil training ou batch, puis passer à production, security ou strict lorsque les règles sont calibrées. Utiliser --max-findings-console pour réduire le bruit en console.

python jcl_doctor_v2.py input/job.jcl \
  --profile training \
  --max-findings-console 10 \
  --html output/reports/job_training_report.html

3. Check-list avant partage externe

Utiliser --redact pour masquer les datasets dans les rapports.
Anonymiser jobnames, user IDs, classes JES, volumes, bibliothèques, applications et préfixes datasets.
Conserver une copie brute interne pour valider le parsing et les findings.
Ne jamais bloquer une mise en production uniquement sur une règle non calibrée : valider avec un expert production.
Enrichir progressivement la policy JSON avec les standards internes.

Point critique : un JCL peut exposer la structure batch et les conventions d’une entreprise. Les exports doivent être traités comme des documents sensibles, surtout avec STEPLIB/JOBLIB, datasets PROD, RACF ou payroll.