Advanced -- 2 hours

Legacy Mainframe Modernization

End-to-end walkthrough covering the full modernization lifecycle: discover COBOL copybook structures, generate modern parsers, create API wrappers, and secure everything with post-quantum cryptography.

What You Will Build

This tutorial walks through a complete mainframe modernization scenario. By the end, you will have:

Phase 1: Discovery

Ingest COBOL copybooks and 3270 terminal traffic, reverse-engineer the data layouts and transaction flows

Phase 2: Translation

Generate modern parsers and REST APIs from the discovered structures, with typed SDKs

Phase 3: Security

Wrap all communication in quantum-safe encryption with zero changes to the mainframe

Phase 4: Operations

Deploy the bridge with monitoring, compliance reporting, and autonomous threat detection

Prerequisites

  • QBITEL Bridge running with all components (see Deploy to Kubernetes)
  • Access to a mainframe environment or our sample COBOL copybooks and 3270 traffic captures
  • Completed the beginner tutorials (Discovery, PQC, Translation Studio)

Phase 1: Discovery

1

Ingest COBOL Copybooks

The Legacy Whisperer module can ingest COBOL copybooks directly to understand record layouts. Upload your copybook files to extract field definitions, PIC clauses, and nested structures. 

# Upload COBOL copybooks for analysis
curl -X POST http://localhost:8000/api/v1/legacy-whisperer/ingest \
  -H "Content-Type: multipart/form-data" \
  -F "copybooks=@CUST-REC.cpy" \
  -F "copybooks=@TRANS-REC.cpy" \
  -F "copybooks=@ACCT-REC.cpy" \
  -F "system_type=mainframe_zos" \
  -F "encoding=EBCDIC"

# Example COBOL copybook (CUST-REC.cpy)
# 01 CUSTOMER-RECORD.
#    05 CUST-ID           PIC 9(10).
#    05 CUST-NAME         PIC X(40).
#    05 CUST-ADDR.
#       10 ADDR-LINE-1    PIC X(30).
#       10 ADDR-LINE-2    PIC X(30).
#       10 CITY           PIC X(20).
#       10 STATE          PIC X(2).
#       10 ZIP-CODE       PIC 9(5).
#    05 ACCT-BALANCE      PIC S9(9)V99 COMP-3.
2

Capture 3270 Terminal Traffic

Capture the TN3270 terminal traffic between users and the mainframe. This reveals the transaction flows, screen navigation sequences, and data exchange patterns that the copybooks alone cannot describe. 

# Capture TN3270 traffic
curl -X POST http://localhost:8000/api/v1/capture/start \
  -H "Content-Type: application/json" \
  -d '{
    "interface": "eth0",
    "filter": "host 10.0.100.5 and port 23",
    "protocol_hint": "tn3270",
    "duration_seconds": 1800,
    "options": {
      "decode_ebcdic": true,
      "track_screen_transitions": true
    }
  }'
3

Run Combined Analysis

Combine the copybook layouts with the captured traffic to build a complete understanding of the mainframe system. The AI correlates data record structures with the transaction flows observed on the wire. 

# Run combined mainframe analysis
curl -X POST http://localhost:8000/api/v1/legacy-whisperer/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "ingest_id": "ing_cobol_001",
    "capture_id": "cap_tn3270_001",
    "analysis_mode": "full",
    "options": {
      "correlate_copybooks": true,
      "map_transactions": true,
      "infer_business_rules": true,
      "generate_data_dictionary": true
    }
  }'

AI-powered correlation: The engine uses neural field detection to match PIC clause definitions from copybooks to the actual byte patterns observed in captured traffic, even when field usage differs from the specification.

Phase 2: Translation

4

Generate Modern Parsers

From the analysis results, generate parsers that can decode the legacy binary formats (EBCDIC-encoded COBOL records, packed decimals, COMP-3 fields) into modern structured data. 

# Generate parsers from analysis
curl -X POST http://localhost:8000/api/v1/translation/rules/generate \
  -H "Content-Type: application/json" \
  -d '{
    "analysis_id": "anl_mainframe_001",
    "output_languages": ["python", "go", "rust"],
    "options": {
      "handle_ebcdic": true,
      "handle_comp3": true,
      "handle_redefines": true,
      "generate_roundtrip": true,
      "include_validation": true
    }
  }'
5

Create REST API Wrappers

Use Translation Studio to wrap the mainframe transactions in a REST API. Each CICS transaction becomes an endpoint, copybook records become JSON schemas, and screen flows become API workflows. 

# Generate REST API from mainframe transactions
curl -X POST http://localhost:8000/api/v1/translation/translate \
  -H "Content-Type: application/json" \
  -d '{
    "analysis_id": "anl_mainframe_001",
    "output_formats": ["openapi"],
    "options": {
      "api_prefix": "/api/v1/mainframe",
      "map_transactions_to_endpoints": true,
      "json_schema_from_copybooks": true,
      "generate_sdks": ["python", "typescript"],
      "include_tests": true
    }
  }'

# Generated endpoint mapping (example)
# POST /api/v1/mainframe/customers         -> CICS INQC transaction
# GET  /api/v1/mainframe/customers/{id}     -> CICS INQC with key
# POST /api/v1/mainframe/transactions       -> CICS TRAN transaction
# GET  /api/v1/mainframe/accounts/{id}/balance -> CICS BALI transaction

Phase 3: Security

6

Enable PQC for Mainframe Traffic

Wrap the mainframe communication channel in quantum-safe encryption. The Protocol Bridge sits between the modern API consumers and the mainframe, adding PQC without any changes to the mainframe itself. 

# Enable PQC on the mainframe bridge channel
curl -X PUT http://localhost:8000/api/v1/channels/ch_mainframe/security \
  -H "Content-Type: application/json" \
  -d '{
    "pqc_enabled": true,
    "profile": "high",
    "encrypt_payload": true,
    "sign_messages": true,
    "field_level_encryption": {
      "enabled": true,
      "fields": ["ACCT-BALANCE", "CUST-SSN", "CUST-DOB"]
    }
  }'

Field-level encryption: Sensitive fields like account balances and personally identifiable information are encrypted individually, so they remain protected even if intermediate systems handle the decrypted message envelope.

Phase 4: Operations

7

Deploy and Monitor

Deploy the complete mainframe bridge with monitoring, compliance reporting, and threat detection enabled. The zero-touch security orchestrator watches for anomalous patterns in mainframe traffic. 

# Deploy the mainframe bridge with full observability
curl -X POST http://localhost:8000/api/v1/translation/translate \
  -H "Content-Type: application/json" \
  -d '{
    "translation_id": "tr_mainframe_001",
    "mode": "bridge",
    "listen_port": 8091,
    "upstream_host": "10.0.100.5",
    "upstream_port": 23,
    "monitoring": {
      "metrics_enabled": true,
      "tracing_enabled": true,
      "anomaly_detection": true,
      "compliance_reporting": ["soc2", "pci_dss"]
    },
    "health_check_interval": "10s"
  }'

# Verify the bridge is operational
curl http://localhost:8091/health

# Test a round-trip transaction through the bridge
curl -X POST http://localhost:8091/api/v1/mainframe/customers \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "customer_id": "1234567890" }'

What You Have Accomplished

  • Reverse-engineered COBOL copybook structures and 3270 transaction flows
  • Generated modern parsers for EBCDIC, COMP-3, and packed decimal formats
  • Created a REST API that translates modern HTTP calls to mainframe CICS transactions
  • Secured all traffic with NIST Level 5 post-quantum cryptography
  • Deployed with monitoring, compliance reporting, and autonomous threat detection
Previous: Compliance Reporting All Tutorials

Modernize Your Mainframe Without Replacing It

QBITEL Bridge wraps legacy systems in modern, quantum-safe APIs without changing a single line of COBOL.

Quick Start Guide Star on GitHub Enterprise Support