Bellacosa Mainframe o mundo da APIs em Python e Mainframe

🔥 “API NÃO É CICS! — O Guia PROIBIDO que Todo Coboleiro Precisa Ler Antes de Virar ‘Júnior’ em Python”

---

☕ Introdução no estilo Bellacosa

Se você vem do mundo do COBOL, acostumado com CICS, MQ, VSAM e chamadas bem estruturadas… prepare-se:

👉 Em Python, o mundo gira em torno de APIs.

E não, não é exagero.

Se no mainframe você faz EXEC CICS LINK, no Python você faz requisições HTTP para APIs REST — e isso muda completamente o jogo.

Hoje você não consome arquivos.
Você consome serviços vivos.

---

🧠 Um pouco de história (porque raiz importa)

Antes de falarmos de Python, vamos entender o conceito:

• Anos 70–90 → Integração via arquivos batch (hello JCL 👋)
• Anos 90–2000 → RPC, CORBA, Web Services SOAP
• Pós-2010 → REST APIs (HTTP simples + JSON)

👉 E aí entra Python como o “canivete suíço” dessa nova era.

A linguagem nasceu em 1991 com Guido van Rossum, mas só explodiu quando virou padrão para:

• automação
• integração
• dados
• e claro… consumo de APIs

---

🚀 O que é API (tradução COBOL)

Pensa assim:

COBOL	Python
CICS LINK	HTTP Request
Copybook	JSON
COMMAREA	Body da requisição
Program	Endpoint

👉 API = um programa remoto que você chama via rede.

---

🔥 As APIs mais usadas em Python (ESSENCIAIS)

1. 🌐 requests — o “EXEC CICS” do Python

A biblioteca mais famosa para consumir APIs.

import requests

response = requests.get("https://api.github.com")
print(response.json())

💡 Tradução Bellacosa:

Isso é basicamente um CALL 'API' USING COMMAREA… só que via internet.

---

2. ⚡ FastAPI — o “CICS moderno”

Se você quer criar APIs:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def home():
    return {"message": "Hello Mainframe!"}

🔥 Extremamente rápido, moderno e tipado.

👉 É tipo montar seu próprio CICS + transaction server, só que leve.

---

3. 🧱 Flask — o clássico minimalista

from flask import Flask

app = Flask(__name__)

@app.route("/")
def home():
    return "Hello COBOL world!"

💡 Muito usado em sistemas menores ou protótipos.

---

4. 🔐 httpx — o “requests turbo”

• Assíncrono (não bloqueia execução)
• Melhor performance

import httpx

response = httpx.get("https://api.github.com")
print(response.json())

👉 Ideal para alta concorrência.

---

5. 🤖 APIs famosas que você VAI usar

• GitHub API
• OpenAI API
• Google Maps API
• AWS APIs

Essas são as “bases de dados modernas”.

---

🧪 Exemplo prático (modo COBOL mindset)

Cenário:

Você quer consultar dados de usuário.

import requests

url = "https://jsonplaceholder.typicode.com/users/1"
response = requests.get(url)

if response.status_code == 200:
    data = response.json()
    print(data["name"])

💡 Pense assim:

• status_code → retorno do programa
• json() → estrutura de dados (tipo copybook dinâmico)

---

⚠️ Pecados capitais do coboleiro em APIs

❌ 1. Esperar estrutura fixa (copybook mental)

JSON muda.

👉 Use:

data.get("campo", "default")

---

❌ 2. Ignorar erro HTTP

if response.status_code != 200:
    print("ERRO!")

👉 Sem isso, você vai quebrar em produção. Certeza.

---

❌ 3. Fazer tudo síncrono (modo batch)

Python moderno usa async.

---

💡 Truques de veterano (ouro puro)

🔥 1. Timeout SEMPRE

requests.get(url, timeout=5)

👉 Evita travar igual job preso em spool.

---

🔥 2. Headers = identidade

headers = {"Authorization": "Bearer TOKEN"}
requests.get(url, headers=headers)

👉 Sem isso, muitas APIs nem respondem.

---

🔥 3. Logging é vida

print(response.text)

👉 Debug de API = olhar payload.

---

🔥 4. Use Postman antes de codar

👉 Teste a API antes. Igual testar JCL antes do PROD.

---

🧠 Curiosidades que poucos sabem

• O termo REST foi criado por Roy Fielding em 2000
• JSON substituiu XML porque é mais leve
• APIs hoje substituem bancos inteiros
• Muitas empresas nem expõem mais DB — só API

👉 Ou seja:
Você não acessa dados.
Você negocia com serviços.

---

🥚 Easter Eggs (pra você brilhar na roda)

🐍 Python tem API embutida para web

import webbrowser
webbrowser.open("https://google.com")

---

🎯 requests aceita JSON direto

requests.post(url, json={"nome": "Bellacosa"})

👉 Sem precisar serializar manualmente.

---

💣 Dá pra mockar API (testes)

from unittest.mock import patch

👉 Igual simular programa no batch.

---

🔥 Conexão com o mundo Mainframe

Você não precisa abandonar COBOL.

👉 Você pode:

• Criar API em Python
• Consumir do COBOL via HTTP (CICS Web Services)
• Integrar legado com cloud

💡 Isso é o futuro real:
Mainframe + APIs + Python

---

🎯 Conclusão estilo Bellacosa

Se você ainda está pensando em arquivo sequencial…

👉 você já está atrasado.

APIs são o novo VSAM.
JSON é o novo copybook.
HTTP é o novo CICS.

E Python?

👉 É a linguagem que cola tudo isso.

---

☕ Frase final pra guardar

“Quem domina API não precisa migrar do mainframe… ele domina o mundo ao redor dele.”

 

Bellacosa Mainframe e o cics rest uma improvavel uniao a ser investigada

☕ Um Café no Bellacosa Mainframe

CICS REST: O Policial Cibernético das APIs Corporativas

Quando um Programador COBOL Descobre que o CICS Pode Patrulhar HTTP, Interrogar JSON e Entregar a COMMAREA Viva ou Morta

Detroit, futuro próximo.

A cidade está mergulhada no caos digital. Aplicativos móveis exigem respostas em milissegundos. Microsserviços atravessam nuvens públicas e privadas. APIs aparecem em cada esquina. Contêineres fogem pelas avenidas do Kubernetes. Mensagens JSON circulam sem documento, sem copybook e, às vezes, sem qualquer respeito pelo contrato de dados.

No subsolo de uma grande corporação financeira, porém, existe uma máquina que nunca dorme.

Ela não usa capa.
Não pilota um Batmóvel.
Não fala em promessas vazias de transformação digital.

Ela executa transações.

Seu nome é CICS Transaction Server.

Durante décadas, ele patrulhou os corredores do processamento corporativo, protegendo contas bancárias, seguradoras, companhias aéreas, governos, cartões de crédito, estoques e sistemas industriais. Agora, diante da invasão das APIs REST, recebeu uma nova diretiva:

Servir o público, proteger a lógica de negócio e fazer o JSON obedecer ao copybook.

Bem-vindo, jovem programador COBOL, ao distrito mais movimentado do IBM Z.

Hoje veremos como um programa COBOL tradicional, acostumado a receber dados por COMMAREA ou CHANNEL, pode ser exposto como uma API REST moderna sem precisar ser completamente reescrito.

Prepare o café. Ajuste o terminal 3270. Verifique o CEMT. O suspeito está chegando pela porta TCP/IP.

---

Diretiva Primária: compreender o problema

Antes de falarmos sobre recursos CICS, precisamos entender o conflito central.

Um programa COBOL tradicional não conhece naturalmente conceitos como:

• URL;

• HTTP;

• HTTPS;

• JSON;

• cabeçalhos;

• métodos GET, POST, PUT e DELETE;

• códigos de status como 200, 400, 404 e 500;

• autenticação por token;

• chamadas originadas por aplicativos móveis.

O programa COBOL normalmente conhece estruturas fixas de dados.

Por exemplo:

01  WS-CLIENTE-REQUEST.
    05 WS-AGENCIA          PIC 9(4).
    05 WS-CONTA            PIC 9(8).
    05 WS-DIGITO           PIC X.

Ele espera receber bytes em posições previamente definidas.

A agência ocupa quatro posições.
A conta ocupa oito.
O dígito ocupa uma.

Não há chaves, aspas, vírgulas nem nomes de propriedades circulando em tempo de execução.

Já uma aplicação web moderna envia algo parecido com:

{
  "agencia": 1234,
  "conta": 87654321,
  "digito": "9"
}

Para um desenvolvedor JavaScript, isso parece natural.

Para um programa COBOL antigo, esse JSON é praticamente um criminoso não identificado entrando na delegacia sem documento.

Alguém precisa fazer a identificação, separar cada campo, validar formatos, converter números e entregar os dados exatamente na posição esperada.

Esse alguém é o CICS.

---

A unidade especial de tradução do CICS

O CICS atua como uma camada intermediária inteligente entre o cliente REST e a aplicação tradicional.

O fluxo básico é:

Cliente externo
      ↓
HTTP ou HTTPS
      ↓
TCPIPSERVICE
      ↓
URIMAP
      ↓
PIPELINE
      ↓
JSON Handler
      ↓
COMMAREA ou CHANNEL
      ↓
Programa COBOL

Na resposta, o caminho é invertido:

Programa COBOL
      ↓
COMMAREA ou CHANNEL
      ↓
JSON Handler
      ↓
JSON
      ↓
Resposta HTTP
      ↓
Cliente externo

O ponto fundamental é este:

O programa COBOL não precisa compreender o documento JSON original.

Ele recebe uma estrutura de dados tradicional, preparada pelo CICS.

Assim, a lógica de negócio pode continuar fazendo aquilo que sempre fez:

• consultar Db2;

• ler VSAM;

• calcular juros;

• validar saldo;

• verificar limites;

• emitir autorizações;

• atualizar cadastros;

• registrar auditoria;

• controlar uma unidade lógica de trabalho.

O CICS cuida do protocolo moderno.
O COBOL cuida do negócio.

Essa separação de responsabilidades é uma das maiores virtudes da arquitetura.

---

Cena 1: o cliente externo chega à cidade

No topo do fluxo temos o consumidor da API.

Ele pode ser:

• um aplicativo Android;

• um aplicativo iOS;

• um portal web;

• um sistema Java;

• um serviço Python;

• um microsserviço no OpenShift;

• uma aplicação hospedada em AWS, Azure ou IBM Cloud;

• uma plataforma de integração;

• o IBM API Connect;

• outro sistema mainframe;

• uma ferramenta de testes como Postman ou curl.

O cliente pode enviar uma requisição como:

POST /api/v1/transferencias
Content-Type: application/json

Corpo:

{
  "contaOrigem": 10012345,
  "contaDestino": 20098765,
  "valor": 250.75
}

Do ponto de vista do cliente, ele está chamando uma API REST comum.

Ele não precisa saber:

• em qual LPAR o CICS está;

• se o programa foi escrito em COBOL;

• se os dados estão em Db2 ou VSAM;

• se a transação utiliza COMMAREA;

• se existe um programa com 30 anos de produção;

• se o serviço participa de uma unidade de trabalho protegida por syncpoint.

Essa transparência é valiosa.

Para a aplicação moderna, o mainframe aparece como um provedor de serviços corporativos.

---

Cena 2: TCPIPSERVICE, o portão blindado

O primeiro recurso CICS relevante é o TCPIPSERVICE.

Pense nele como o portão de entrada do distrito.

Ele define onde o CICS escutará conexões TCP/IP.

Entre suas responsabilidades estão:

• porta de escuta;

• protocolo utilizado;

• suporte a HTTP ou HTTPS;

• configuração de SSL/TLS;

• associação com parâmetros de segurança;

• controle da entrada de conexões.

Exemplo conceitual:

Porta: 8443
Protocolo: HTTP
SSL: habilitado
Status: aberto

Quando o cliente chama:

https://api.empresa.com:8443/api/v1/saldo

a conexão chega ao TCPIPSERVICE correspondente.

Sem TCPIPSERVICE ativo, ninguém entra.

É como tentar apresentar uma denúncia em uma delegacia cujo portão está fechado.

Dica Bellacosa

Quando um serviço não responde, não comece imediatamente alterando o COBOL.

Verifique primeiro:

1. O TCPIPSERVICE está instalado?

2. Está habilitado?

3. Está escutando na porta correta?

4. Existe firewall bloqueando?

5. O certificado TLS é válido?

6. O host e a porta da chamada estão corretos?

Muitos “erros do programa” são, na verdade, problemas anteriores ao programa.

O suspeito sequer chegou à sala de interrogatório.

---

Cena 3: URIMAP, o reconhecimento facial das URLs

Depois que a requisição entra no CICS, é necessário descobrir qual serviço deve tratá-la.

Essa é uma das funções do URIMAP.

O URIMAP relaciona um padrão de URI a um recurso ou fluxo CICS.

Por exemplo:

/api/v1/clientes/*

ou:

/api/v1/saldos/*

Ele funciona como uma tabela de encaminhamento.

Quando chega:

GET /api/v1/clientes/12345

o CICS verifica qual URIMAP corresponde àquele endereço.

Em termos conceituais:

URI recebida
      ↓
Comparação com URIMAPs
      ↓
Seleção do pipeline ou serviço

O URIMAP também pode ajudar a separar versões:

/api/v1/clientes
/api/v2/clientes

Isso é importante porque APIs evoluem.

Talvez a versão 1 retorne:

{
  "nome": "MURPHY"
}

e a versão 2 retorne:

{
  "nomeCompleto": "ALEX MURPHY",
  "status": "ATIVO"
}

Manter versões evita que uma mudança destrua consumidores antigos.

Curiosidade investigativa

Em arquiteturas web como Spring Boot, rotas podem ser definidas com anotações:

@GetMapping("/clientes/{id}")

No CICS, o conceito de roteamento aparece por meio de recursos como URIMAP, pipelines e handlers.

A tecnologia muda.
A necessidade arquitetural permanece.

Alguém sempre precisa decidir quem atende cada endereço.

---

Cena 4: PIPELINE, a linha de processamento

O PIPELINE é a linha de montagem que conduz a mensagem pelos componentes necessários.

Imagine uma esteira industrial da Omni Consumer Products, mas sem o protótipo ED-209 disparando contra os programadores durante a reunião.

A requisição passa por estágios:

HTTP
  ↓
Identificação do serviço
  ↓
Tratamento da mensagem
  ↓
Conversão do JSON
  ↓
Chamada da aplicação
  ↓
Conversão da resposta

O pipeline não é apenas uma “seta” no desenho.

Ele representa a infraestrutura que organiza o processamento da mensagem.

Dependendo da configuração, podem existir etapas relacionadas a:

• transformação de dados;

• validação;

• segurança;

• tratamento de cabeçalhos;

• seleção de handlers;

• geração da resposta;

• registro de erros.

É importante não confundir o pipeline com o programa de negócio.

O pipeline é a rota operacional.
O programa COBOL é o policial que executa a investigação.

---

Cena 5: o JSON Handler interroga a mensagem

O cliente envia:

{
  "codigoCliente": 4711,
  "valor": 850.25,
  "moeda": "BRL"
}

O programa COBOL espera:

01  WS-REQUEST.
    05 WS-CODIGO-CLIENTE   PIC 9(8).
    05 WS-VALOR            PIC S9(9)V99 COMP-3.
    05 WS-MOEDA            PIC X(3).

Essas representações não são iguais.

O JSON representa números e textos de forma lógica.

O COBOL pode representar números em:

• display;

• binário;

• packed decimal;

• COMP;

• COMP-3;

• campos com sinal;

• casas decimais implícitas.

O JSON Handler realiza a tradução entre esses formatos.

Exemplo:

"valor": 850.25

pode ser convertido para um campo:

PIC S9(9)V99 COMP-3

O programa recebe o valor na forma adequada para o processamento COBOL.

Na resposta ocorre o contrário.

Se o programa devolver:

WS-SALDO PIC S9(9)V99 COMP-3 VALUE 150075

considerando as casas decimais implícitas, o handler poderá produzir:

{
  "saldo": 1500.75
}

A conversão exige regras.

Essas regras são geradas a partir da definição das estruturas.

E aqui entram os assistentes do CICS.

---

DFHLS2JS e DFHJS2LS: a reconstrução cibernética dos dados

Dois nomes aparecem frequentemente quando estudamos JSON no CICS:

• DFHLS2JS

• DFHJS2LS

À primeira vista, parecem números de série de unidades mecanizadas da polícia de Detroit.

Mas são utilitários fundamentais.

DFHLS2JS

O nome pode ser lido como:

Language Structure to JSON

Ou seja:

Estrutura de linguagem
        ↓
Definição JSON

Você fornece uma estrutura COBOL, PL/I ou outra linguagem suportada.

O utilitário gera artefatos que permitem mapear aquela estrutura para JSON.

Por exemplo, a partir de:

01  CLIENTE-RESPONSE.
    05 CLIENTE-ID          PIC 9(8).
    05 CLIENTE-NOME        PIC X(40).
    05 CLIENTE-SALDO       PIC S9(9)V99 COMP-3.

pode ser criada uma representação lógica equivalente a:

{
  "clienteId": 12345678,
  "clienteNome": "ALEX MURPHY",
  "clienteSaldo": 4900.50
}

DFHJS2LS

O sentido principal é:

JSON to Language Structure

Ele parte de uma definição JSON e gera estruturas ou mapeamentos adequados para a linguagem.

Isso é útil quando o contrato JSON já existe e a aplicação CICS precisa se adaptar a ele.

Portanto, existem dois caminhos de desenvolvimento.

Caminho bottom-up

Você já possui o programa COBOL e o copybook.

Parte da estrutura existente e gera a interface JSON.

Copybook COBOL
       ↓
DFHLS2JS
       ↓
Artefatos JSON e binding

Caminho top-down

Você já possui o contrato JSON ou o desenho da API.

Parte do contrato e gera uma estrutura de linguagem correspondente.

Definição JSON
       ↓
DFHJS2LS
       ↓
Estrutura COBOL e binding

A escolha depende de onde está a fonte da verdade.

Em sistemas legados, muitas vezes o copybook existente é o ponto de partida.

Em projetos API-first, o contrato JSON pode ser definido antes da implementação.

---

O arquivo de binding: a memória operacional

O web service binding file contém informações de mapeamento necessárias para que o CICS converta a mensagem.

Ele funciona como uma espécie de memória operacional da reconstrução.

Diz ao CICS, em essência:

• qual campo JSON corresponde a qual campo COBOL;

• como tratar tipos;

• como converter representações;

• como montar a estrutura de entrada;

• como transformar a estrutura de saída.

Esse arquivo costuma ser armazenado no zFS, o sistema de arquivos UNIX do z/OS.

O CICS acessa os artefatos durante o processamento.

Atenção

O binding não é simplesmente documentação.

Ele participa efetivamente da execução.

Se houver inconsistência entre:

• o copybook utilizado na geração;

• o programa compilado;

• o binding implantado;

o resultado pode ser desastroso.

Campos podem ser interpretados com tamanhos errados.
Valores podem chegar deslocados.
Conversões podem falhar.
O programa pode receber dados aparentemente válidos, mas incorretos.

Essa é uma ocorrência particularmente perigosa porque nem sempre provoca ABEND imediato.

Às vezes, o dado errado passa pela porta usando um crachá aparentemente válido.

---

COMMAREA ou CHANNEL: escolha seu compartimento

Depois da conversão, o CICS precisa entregar os dados à aplicação.

Dois modelos são comuns:

• COMMAREA;

• CHANNEL e CONTAINER.

COMMAREA

A COMMAREA é o método clássico.

Ela consiste em uma área contínua de memória passada entre programas ou transações.

Exemplo conceitual:

01 DFHCOMMAREA.
   05 CA-FUNCAO          PIC X.
   05 CA-CLIENTE         PIC 9(8).
   05 CA-STATUS          PIC X(2).

Vantagens:

• simples;

• conhecida por praticamente todos os programadores CICS;

• amplamente utilizada;

• adequada para estruturas pequenas e estáveis.

Limitações:

• tamanho limitado;

• uma única área linear;

• maior dificuldade para mensagens complexas;

• mudanças podem afetar offsets e compatibilidade.

A COMMAREA tradicional possui um limite próximo de 32 KB, associado ao tamanho permitido no modelo clássico de comunicação.

CHANNEL e CONTAINER

O CHANNEL organiza múltiplos containers.

Exemplo:

CHANNEL: API-CHANNEL

CONTAINER: REQUEST
CONTAINER: RESPONSE
CONTAINER: METADATA
CONTAINER: ERROR-INFO

Vantagens:

• melhor organização;

• suporte a volumes maiores;

• separação lógica dos dados;

• flexibilidade;

• menor dependência de uma única estrutura monolítica.

Para novos desenhos, CHANNEL e CONTAINER costumam oferecer uma arquitetura mais limpa.

Contudo, não significa que toda COMMAREA deva ser imediatamente substituída.

A regra Bellacosa é:

Não modernize destruindo o que funciona. Modernize criando fronteiras melhores.

Se o programa existente funciona corretamente com COMMAREA, uma camada de exposição pode preservar essa interface.

Se uma nova aplicação estiver sendo criada, CHANNEL e CONTAINER merecem forte consideração.

---

Cena 6: o programa COBOL entra em ação

Após a conversão, o CICS chama o programa de aplicação.

Ele pode receber:

01  REQUEST-DATA.
    05 REQUEST-CONTA      PIC 9(8).
    05 REQUEST-VALOR      PIC S9(9)V99 COMP-3.

O programa executa sua lógica:

IF REQUEST-VALOR <= SALDO-DISPONIVEL
    MOVE '00' TO RESPONSE-CODE
    SUBTRACT REQUEST-VALOR
        FROM SALDO-ATUAL
ELSE
    MOVE '51' TO RESPONSE-CODE
END-IF

Observe que não há nenhuma instrução para interpretar JSON.

Não existe:

PARSE JSON MANUALMENTE

O código se concentra no domínio do negócio.

Esse é o objetivo.

Contudo, algumas versões modernas do Enterprise COBOL também oferecem recursos próprios para processamento JSON. Isso pode ser útil em certos cenários, mas não elimina necessariamente o valor da infraestrutura CICS de pipelines, assistentes e bindings.

Existem duas filosofias:

Conversão na infraestrutura

CICS converte
Programa recebe estrutura pronta

Conversão na aplicação

Programa recebe JSON
Programa executa JSON PARSE

Para exposição padronizada de serviços CICS, a conversão na infraestrutura costuma reduzir acoplamento e manter o programa focado no negócio.

---

Cena 7: a resposta sai patrulhando a rede

O programa preenche a estrutura de saída:

01  RESPONSE-DATA.
    05 RESPONSE-CODE      PIC X(2).
    05 RESPONSE-MESSAGE   PIC X(60).
    05 RESPONSE-BALANCE   PIC S9(9)V99 COMP-3.

Exemplo:

RESPONSE-CODE    = 00
RESPONSE-MESSAGE = TRANSFERENCIA APROVADA
RESPONSE-BALANCE = 3250.25

O JSON Handler converte para:

{
  "codigo": "00",
  "mensagem": "TRANSFERENCIA APROVADA",
  "saldo": 3250.25
}

O CICS então envia uma resposta HTTP.

Exemplo:

HTTP/1.1 200 OK
Content-Type: application/json

O cliente recebe a resposta sem saber quantas camadas corporativas participaram do processamento.

Mas aqui existe uma decisão importante:

Um código de negócio não é automaticamente um código HTTP.

Por exemplo:

Código 51 = saldo insuficiente

Isso não significa necessariamente:

HTTP 500

Saldo insuficiente é uma resposta válida da regra de negócio. O serviço funcionou corretamente.

Dependendo do contrato da API, pode ser retornado:

HTTP 422 Unprocessable Content

ou até:

HTTP 200 OK

com:

{
  "aprovado": false,
  "motivo": "SALDO_INSUFICIENTE"
}

A escolha depende do padrão arquitetural da organização.

Regra prática

• Erro de formato enviado pelo cliente: 400 Bad Request;

• credencial ausente ou inválida: 401 Unauthorized;

• acesso proibido: 403 Forbidden;

• recurso inexistente: 404 Not Found;

• conflito de estado: 409 Conflict;

• regra de negócio não processável: frequentemente 422;

• falha inesperada no servidor: 500 Internal Server Error;

• serviço temporariamente indisponível: 503 Service Unavailable.

Não transforme todo problema de negócio em erro técnico.

O ED-209 não precisa disparar porque o cliente digitou um código inválido.

---

Passo a passo de uma modernização controlada

Agora vamos construir um roteiro prático.

Passo 1: escolha uma operação pequena

Não comece expondo o fechamento contábil completo da empresa.

Escolha uma função simples e bem conhecida:

• consultar cliente;

• consultar saldo;

• obter status;

• listar produtos;

• validar cadastro.

Operações de consulta são bons primeiros candidatos porque apresentam menor risco transacional.

---

Passo 2: localize o programa e sua interface

Descubra:

• nome do programa;

• transação associada;

• copybook de entrada;

• copybook de saída;

• uso de COMMAREA ou CHANNEL;

• tamanho dos dados;

• chamadas a Db2, VSAM, MQ ou outros programas;

• códigos de retorno;

• requisitos de segurança.

Documente o contrato atual antes de criar o novo.

Modernização sem inventário é patrulhamento sem mapa.

---

Passo 3: higienize o copybook

Verifique:

• campos redefinidos;

• REDEFINES;

• OCCURS DEPENDING ON;

• campos binários;

• packed decimal;

• sinais;

• campos filler;

• nomes duplicados;

• estruturas condicionais;

• caracteres especiais;

• campos de comprimento variável.

Nem toda estrutura COBOL antiga foi criada pensando em exposição externa.

Pode ser melhor criar um copybook de API separado.

Exemplo:

01 API-SALDO-REQUEST.
   05 API-CONTA          PIC 9(8).

01 API-SALDO-RESPONSE.
   05 API-CODIGO         PIC X(2).
   05 API-SALDO          PIC S9(9)V99 COMP-3.

Essa estrutura pode chamar internamente o programa legado.

Assim, você cria uma fachada estável.

---

Passo 4: defina o contrato REST

Decida:

GET /api/v1/contas/{conta}/saldo

Resposta:

{
  "conta": 12345678,
  "saldo": 1750.40,
  "moeda": "BRL"
}

Defina também:

• campos obrigatórios;

• tamanhos máximos;

• valores permitidos;

• formato de datas;

• precisão decimal;

• códigos HTTP;

• mensagens de erro;

• versão da API.

O copybook não deve ser publicado cegamente como contrato externo.

Um nome interno como:

WS-X9-COD-CLI-BASE

não é um bom nome de propriedade JSON.

Prefira algo compreensível:

"codigoCliente"

---

Passo 5: gere os artefatos

Use o assistente apropriado:

• DFHLS2JS para partir da estrutura de linguagem;

• DFHJS2LS para partir do JSON.

A geração pode produzir:

• schemas;

• bindings;

• estruturas;

• metadados de conversão;

• arquivos de configuração.

Em muitos ambientes, o CICS Explorer facilita esse processo.

Um wizard pode criar um CICS Bundle a partir de um programa existente.

Isso reduz a necessidade de preparar manualmente todos os recursos e jobs.

Mas atenção:

Wizard não substitui entendimento.

Ele automatiza passos.
Não decide por você se o contrato da API é bom.

---

Passo 6: configure os recursos CICS

Você precisará garantir que os elementos estejam corretamente definidos e instalados:

• TCPIPSERVICE;

• URIMAP;

• PIPELINE;

• WEBSERVICE ou recursos relacionados;

• diretórios no zFS;

• bundle;

• programa;

• transação, quando aplicável;

• segurança.

Use o CICS Explorer, definições CSD, bundles ou o método adotado pela organização.

---

Passo 7: teste com ferramentas externas

Teste primeiro fora da aplicação final.

Exemplo com curl:

curl -X POST \
  https://host.exemplo.com/api/v1/saldos \
  -H "Content-Type: application/json" \
  -d '{"conta":12345678}'

Valide:

• status HTTP;

• conteúdo da resposta;

• headers;

• tempo de resposta;

• comportamento com dados inválidos;

• campos ausentes;

• números fora da faixa;

• caracteres especiais;

• falha do programa;

• indisponibilidade de banco de dados.

Não teste apenas o caminho feliz.

Todo criminoso digital parece inocente quando recebe apenas dados perfeitos.

---

CICS como REST Requester: o policial também faz chamadas

Até agora vimos o CICS como service provider.

Ou seja:

Cliente externo chama o CICS

Mas o CICS também pode atuar como solicitante:

Programa CICS chama serviço externo

Imagine um programa COBOL que precise consultar:

• cotação de moeda;

• serviço antifraude;

• validação de endereço;

• geolocalização;

• serviço de identidade;

• API de parceiros;

• serviço de nuvem;

• motor de inteligência artificial corporativo.

O fluxo pode ser:

Programa COBOL
      ↓
CICS
      ↓
HTTP
      ↓
API externa
      ↓
Resposta JSON
      ↓
Conversão
      ↓
Estrutura COBOL

O CICS pode usar comandos e recursos de cliente HTTP para construir e enviar requisições.

Em cenários específicos, o programa pode trabalhar com:

• EXEC CICS WEB OPEN;

• EXEC CICS WEB CONVERSE;

• EXEC CICS WEB SEND;

• EXEC CICS WEB RECEIVE;

• URIMAP do tipo cliente;

• conexões TLS;

• tratamento de headers.

A implementação exata depende da versão do CICS, da arquitetura e da estratégia adotada.

É importante entender que o lado requester não é simplesmente o diagrama provider virado ao contrário.

Os conceitos são simétricos, mas os recursos, comandos e responsabilidades de programação podem mudar.

---

Segurança: diretiva que não pode ser apagada

Expor um programa COBOL como REST não significa abrir a porta do mainframe para qualquer pessoa.

A API deve considerar:

• TLS;

• certificados;

• autenticação;

• autorização;

• RACF;

• proteção das transações;

• proteção dos recursos;

• validação de entrada;

• limitação de chamadas;

• auditoria;

• mascaramento de informações sensíveis;

• API gateway;

• tokens;

• logs seguros.

Uma arquitetura comum pode ser:

Cliente
   ↓
API Gateway
   ↓
Autenticação e políticas
   ↓
CICS
   ↓
Programa COBOL

O IBM API Connect pode atuar como camada de gerenciamento, aplicando:

• segurança;

• quotas;

• analytics;

• controle de versões;

• portal para desenvolvedores;

• políticas de tráfego.

O CICS continua executando a transação, enquanto o gateway controla a exposição externa.

Cuidado com logs

Não grave indiscriminadamente:

• CPF;

• senha;

• token;

• número completo de cartão;

• dados bancários;

• informações médicas;

• chaves privadas.

Log de diagnóstico não deve virar arquivo de evidências contra a própria empresa.

---

Curiosidades da delegacia CICS

1. CICS não é apenas uma “tela verde”

Muitos iniciantes associam CICS exclusivamente a mapas BMS e terminais 3270.

Mas o CICS moderno pode atender:

• aplicações web;

• APIs;

• Java;

• JSON;

• SOAP;

• eventos;

• mensageria;

• integração com cloud;

• workloads híbridos.

A tela 3270 é apenas uma das interfaces possíveis.

---

2. REST não obriga reescrita completa

Modernizar não significa necessariamente transportar toda a lógica para outra plataforma.

Muitas vezes, uma boa modernização consiste em:

Criar uma API estável
        ↓
Preservar a lógica confiável
        ↓
Substituir partes gradualmente

Isso reduz risco.

Reescrever milhões de linhas de COBOL apenas para produzir JSON pode ser economicamente irresponsável.

---

3. Copybook também é contrato

O copybook descreve mais do que campos.

Ele carrega decisões históricas:

• tamanho de conta;

• precisão monetária;

• códigos;

• indicadores;

• datas;

• flags;

• estruturas repetitivas.

Ao expor uma API, você está transformando parte desse contrato interno em contrato externo.

Faça isso conscientemente.

---

4. JSON é flexível; COBOL é preciso

JSON aceita estruturas dinâmicas.

COBOL prefere estruturas rigorosamente definidas.

Isso não é defeito.

É uma diferença filosófica.

Em sistemas financeiros, precisão de posição, tamanho e decimal é uma vantagem.

O CICS cria uma ponte entre a flexibilidade externa e a disciplina interna.

---

Erros clássicos que o programador deve evitar

Expor diretamente a COMMAREA inteira

Uma COMMAREA pode conter:

• campos internos;

• fillers;

• controles;

• dados sensíveis;

• flags técnicas;

• áreas de trabalho;

• códigos incompreensíveis para consumidores externos.

Crie uma interface própria para API.

---

Ignorar versionamento

Alterar um campo pode quebrar dezenas de consumidores.

Use versões e contratos claros.

---

Misturar erro técnico com erro de negócio

“Cliente não possui saldo” não é necessariamente uma pane no servidor.

---

Não validar números

Um valor JSON pode ultrapassar a capacidade de um PIC 9(5).

Valide limites antes da lógica de negócio.

---

Esquecer a codificação de caracteres

O mainframe trabalha frequentemente com EBCDIC; clientes web trabalham geralmente com UTF-8.

Conversões precisam estar corretamente configuradas.

Problemas de encoding podem transformar:

JOÃO

em um relatório digno do arquivo de ocorrências inexplicáveis.

---

Alterar copybook sem regenerar binding

Se a estrutura mudou, o mapeamento pode precisar ser regenerado e redistribuído.

Binding antigo com programa novo é receita para corrupção silenciosa.

---

Easter eggs para os veteranos do cinema e do mainframe

Em algum lugar da região CICS, um sysprog observa o painel e murmura:

Eu compraria essa API por um dólar.

Na sala ao lado, um desenvolvedor tenta enviar um JSON com campo numérico maior que o PIC suporta. O handler responde com a firmeza de um policial cibernético:

Dead or alive, you are coming with me.

O JSON, naturalmente, escolhe o 400 Bad Request.

Enquanto isso, uma reunião executiva promete substituir todo o mainframe em seis meses. No fundo da sala, o veterano do CICS apenas olha para o relatório de disponibilidade, toma um café e aguarda o próximo episódio.

Ele já viu esse filme antes.

Talvez mais de uma vez.

---

Conclusão: a quarta diretiva do CICS

O CICS Transaction Server não sobreviveu por permanecer parado.

Ele sobreviveu porque evoluiu sem abandonar seus fundamentos:

• integridade;

• desempenho;

• segurança;

• controle transacional;

• escalabilidade;

• compatibilidade;

• proteção da lógica de negócio.

Ao fornecer suporte a REST e JSON, o CICS não obrigou o COBOL a fingir que é JavaScript.

Ele criou uma camada especializada de tradução.

O cliente envia HTTP e JSON.
O TCPIPSERVICE recebe a conexão.
O URIMAP identifica o caminho.
O PIPELINE conduz o processamento.
O JSON Handler converte a mensagem.
A COMMAREA ou o CHANNEL entrega os dados.
O programa COBOL executa a regra de negócio.
A resposta percorre o caminho inverso.

Tudo isso permite que um aplicativo moderno converse com uma aplicação escrita décadas atrás como se estivesse chamando qualquer outro serviço contemporâneo.

Essa é a verdadeira modernização pragmática.

Não é destruir o passado.
É colocar uma interface moderna diante dele.

Não é substituir um sistema confiável apenas porque sua linguagem é antiga.
É permitir que ele participe de arquiteturas atuais.

Não é esconder o mainframe por vergonha.
É transformá-lo em um provedor de serviços corporativos.

O jovem programador COBOL entra na sala pensando que encontrará apenas COMMAREA, BMS e terminal 3270.

Sai de lá compreendendo URIs, pipelines, bindings, JSON, TLS, APIs e integração híbrida.

No visor do CICS aparece a mensagem final:

SERVICE STATUS: ENABLED
PIPELINE STATUS: ACTIVE
PROGRAM STATUS: AVAILABLE
HTTP RESPONSE: 200 OK

A cidade digital pode continuar operando.

O JSON foi processado.
O COBOL permaneceu intacto.
A transação foi concluída.

E, em algum lugar do z/OS, a verdadeira quarta diretiva continua protegida:

Nunca interromper o processamento de produção.

 

Bellacosa Mainframe e o zos connect

☕ Um Café no Bellacosa Mainframe

Sherlock Holmes, COBOL e o Mistério da API que Entrou no CICS sem Conhecer COMMAREA

🔎 z/OS Connect, REST, JSON, OpenAPI, CICS, IMS, Db2, segurança, modernização e o curioso caso em que Watson jurava que o legado precisava morrer — até Holmes encontrar uma porta chamada API

Londres, 221B Baker Street.

Chovia.

Naturalmente chovia.

Toda boa investigação envolvendo sistemas legados começa com chuva, café frio e alguém dizendo:

— Holmes, temos um problema grave.

Sherlock Holmes não levantou os olhos do terminal 3270.

— Grave, Watson?

— Gravíssimo. A diretoria descobriu APIs.

Holmes parou.

A sala ficou em silêncio.

Até o JES2 pareceu diminuir o número de mensagens no console.

Watson continuou:

— Agora querem modernizar tudo.

— Naturalmente.

— Disseram que temos de substituir o COBOL.

Holmes finalmente virou a cadeira.

— E qual é o problema do sistema atual?

Watson consultou as anotações.

— Processa milhões de transações por dia, roda há vinte anos, tem disponibilidade excelente, regras de negócio consolidadas, integração com CICS e Db2 e praticamente ninguém sabe exatamente tudo que ele faz.

Holmes acendeu imaginariamente seu cachimbo.

— Então, Watson, já temos nosso primeiro suspeito.

— O COBOL?

— Não. A palavra modernização.

E assim começa nossa investigação.

Porque uma das coisas mais interessantes sobre o IBM z/OS Connect é justamente esta: ele nos obriga a separar duas coisas que muita apresentação corporativa insiste em colocar dentro da mesma mala.

Modernizar não é necessariamente reescrever.

Às vezes o sistema já está fazendo exatamente aquilo que deveria fazer.

O problema é apenas que ninguém do lado de fora consegue conversar com ele usando as interfaces modernas que o restante da empresa adotou.

E é aí que entra o z/OS Connect.

---

O cadáver não estava morto

Vamos começar pelo mistério clássico.

Você possui um programa COBOL.

Algo parecido com isto:

IDENTIFICATION DIVISION.
PROGRAM-ID. CONSULTA-SALDO.

DATA DIVISION.

WORKING-STORAGE SECTION.

01 WS-CONTA       PIC 9(08).
01 WS-SALDO       PIC S9(11)V99 COMP-3.
01 WS-LIMITE      PIC S9(11)V99 COMP-3.
01 WS-STATUS      PIC X(01).

PROCEDURE DIVISION.

    PERFORM CONSULTAR-CONTA
    PERFORM CALCULAR-LIMITE
    PERFORM RETORNAR-DADOS
    GOBACK.

O programa funciona.

Ele talvez seja executado dentro do CICS.

Talvez consulte Db2.

Talvez utilize uma COMMAREA.

Talvez faça parte de uma transação que existe desde uma época em que telefone celular parecia um tijolo usado para ligar para Gordon Gekko.

Durante anos, o acesso era feito por uma aplicação 3270.

Algo como:

USUÁRIO
   |
   v
TERMINAL 3270
   |
   v
CICS
   |
   v
COBOL
   |
   v
Db2

Perfeito.

Até que chegou o aplicativo mobile.

O novo desenvolvedor pergunta:

— Qual endpoint devo chamar para consultar saldo?

O COBOLzeiro responde:

— Endpoint?

— Sim. Algo como:

GET /accounts/123456/balance

— Rapaz, eu tenho uma COMMAREA.

E os dois se observam como arqueólogos de civilizações diferentes.

É exatamente esse tipo de fronteira tecnológica que o z/OS Connect ajuda a resolver.

---

A primeira pista: o que é z/OS Connect?

Em termos simples, o IBM z/OS Connect permite conectar recursos do z/OS ao universo de APIs.

Isso significa criar uma ponte entre tecnologias como:

COBOL
CICS
IMS
Db2
z/OS

e o universo:

HTTP
REST
JSON
OpenAPI
OAuth
JWT
Cloud
Mobile
Web
Kubernetes

Visualmente:

Aplicação Web
     |
Aplicação Mobile
     |
Microsserviço
     |
Sistema Cloud
     |
     v
 REST / JSON
     |
     v
+----------------+
| z/OS Connect   |
+----------------+
     |
     +------ CICS
     |
     +------ IMS
     |
     +------ aplicações z/OS
     |
     v
   COBOL
     |
     v
    Db2

Para Sherlock Holmes, isso seria a primeira evidência importante.

O COBOL não desapareceu.

Apenas ganhou um intérprete na porta.

---

Watson comete o primeiro erro: “Então z/OS Connect é um API Gateway?”

Não exatamente.

Esse é um daqueles erros suficientemente próximos da verdade para parecer corretos.

O z/OS Connect possui funções relacionadas a APIs, segurança e integração, mas sua função mais importante deve ser entendida como:

ligar APIs ao mundo z/OS.

Em uma arquitetura corporativa real, pode existir algo assim:

Internet
   |
   v
API Gateway corporativo
   |
   v
z/OS Connect
   |
   v
CICS
   |
   v
COBOL

O API Gateway pode cuidar de coisas como:

• exposição externa;

• políticas corporativas;

• rate limiting;

• analytics;

• controle de consumidores;

• roteamento;

• autenticação de borda.

Enquanto o z/OS Connect trabalha próximo dos recursos do IBM Z.

Holmes provavelmente diria:

“Não confunda o mordomo com a porta da mansão, Watson. Ambos controlam quem entra, mas desempenham funções diferentes.”

---

API Provider: quando o mainframe oferece um serviço

Agora entramos em uma das funções mais importantes.

Imagine um CICS contendo transações como:

INQC  Consulta Cliente
INQS  Consulta Saldo
BLKC  Bloqueia Cartão
LIMC  Consulta Limite

No mundo antigo, uma aplicação talvez precisasse conhecer detalhes específicos do backend.

No mundo das APIs, podemos criar algo mais amigável:

GET /clientes/{id}

GET /contas/{id}/saldo

POST /cartoes/{id}/bloqueio

GET /cartoes/{id}/limite

Uma aplicação mobile poderia executar:

GET /contas/778899/saldo

E receber:

{
  "conta": "778899",
  "saldo": 28453.72,
  "moeda": "BRL"
}

Por trás disso:

Mobile
  |
  | HTTPS
  v
z/OS Connect
  |
  v
CICS
  |
  v
COBOL
  |
  v
Db2

A parte fascinante é esta:

o aplicativo não precisa saber que existe CICS.

E o COBOL não precisa saber que existe smartphone.

Cada lado trabalha dentro de seu próprio universo tecnológico.

Esse desacoplamento é uma das grandes virtudes da arquitetura.

---

Uma COMMAREA entra em Baker Street

Watson recebe uma estrutura COBOL:

01 DFHCOMMAREA.

   05 CA-ACCOUNT     PIC 9(08).
   05 CA-CUSTOMER    PIC X(40).
   05 CA-BALANCE     PIC S9(11)V99 COMP-3.
   05 CA-LIMIT       PIC S9(11)V99 COMP-3.
   05 CA-STATUS      PIC X(01).

Do outro lado chega:

{
  "account": "12345678"
}

Watson pergunta:

— Holmes, como esse JSON vai entrar nessa estrutura?

Holmes aponta para o quadro.

É justamente aqui que entra o conceito de mapeamento e transformação de dados.

Porque os dois mundos possuem representações diferentes.

JSON entende coisas como:

string
number
boolean
array
object
null

COBOL possui:

PIC X
PIC 9
COMP
COMP-3
OCCURS
REDEFINES
SIGN

Imagine:

05 BALANCE PIC S9(11)V99 COMP-3.

Isso não é simplesmente “um número”.

Existe representação interna.

Existe sinal.

Existe escala decimal.

Existe formato binário ou decimal compactado dependendo da declaração.

Portanto, converter:

{
  "balance": 1500.75
}

para uma estrutura COBOL envolve entender tipos e representação.

Não é magia.

É integração.

---

Easter egg nº 1: COMP-3 continua assustando quem vem da web

Um desenvolvedor JavaScript olha:

PIC S9(09)V99 COMP-3

e talvez pense:

“Por que o número está vestido de hieróglifo?”

O programador COBOL olha:

const value = data?.customer?.accounts?.[0]?.balance ?? 0;

e pensa exatamente a mesma coisa.

Cada geração cria sua própria magia negra.

---

OpenAPI: a ficha policial da API

Sherlock Holmes gostava de arquivos.

Dossiês.

Registros.

Descrições precisas.

OpenAPI provavelmente seria uma de suas tecnologias favoritas.

OpenAPI é uma especificação para descrever APIs HTTP.

Por exemplo:

paths:

  /accounts/{accountId}/balance:

    get:

      summary: Returns account balance

      parameters:

        - name: accountId
          in: path
          required: true

      responses:

        '200':
          description: Account found

        '404':
          description: Account not found

Esse arquivo pode descrever:

• endpoints;

• parâmetros;

• métodos HTTP;

• request;

• response;

• códigos de retorno;

• schemas;

• tipos de dados.

Para um programador COBOL iniciante, podemos fazer uma analogia.

Uma copybook define:

estrutura de dados

OpenAPI define:

estrutura da conversa.

A copybook responde:

“Como os dados estão organizados?”

OpenAPI responde:

“Como alguém chama esse serviço e o que ele recebe de volta?”

Não são equivalentes.

Mas ambos cumprem a função importantíssima de estabelecer contratos.

---

API-first: Holmes começa pela pergunta correta

Durante muitos anos, projetos de integração começavam assim:

Temos o programa ABC123. Como transformamos isso em uma API?

Funciona.

Mas arquiteturas modernas cada vez mais preferem começar de outra maneira:

Qual serviço o negócio precisa?

Imagine que precisamos oferecer consulta de saldo.

Primeiro definimos:

GET /accounts/{id}/balance

Depois definimos o retorno:

{
   "account": "123456",
   "availableBalance": 1800.42,
   "currency": "BRL"
}

Só depois perguntamos:

Quem implementará isso?

Talvez:

CICS + COBOL

Talvez:

IMS

Talvez:

Db2

Talvez daqui a dez anos:

outra implementação.

O consumidor não precisa necessariamente saber.

Este é o poder de um contrato bem definido.

---

O grande mistério: modernização sem reescrita

Aqui chegamos ao coração do caso.

Considere um programa COBOL com:

25 anos de produção

4.000 regras de negócio

dezenas de integrações

tratamentos de exceção

rotinas fiscais

regras contábeis

auditoria

segurança

controle transacional

Alguém entra em uma reunião e diz:

— Precisamos reescrever porque é legado.

Holmes pergunta:

— O sistema está errado?

— Não.

— Está lento?

— Não.

— É instável?

— Não.

— Não suporta o volume?

— Suporta.

— Então por que reescrever?

— Porque não é moderno.

Silêncio.

Esse é exatamente o ponto no qual tecnologias como z/OS Connect ficam interessantes.

Talvez você não precise substituir:

COBOL

Talvez precise substituir:

a maneira como os consumidores acessam o COBOL.

Veja a diferença:

ANTES

3270
 |
 v
CICS
 |
 v
COBOL

Depois:

Mobile
Web
Cloud
Parceiro
Kubernetes
    |
    v
REST API
    |
    v
z/OS Connect
    |
    v
CICS
    |
    v
COBOL

A lógica continua funcionando.

A interface muda.

Isso é modernização por integração.

---

Mas Holmes encontra pegadas indo na direção contrária

Até agora falamos de aplicações externas chamando o mainframe.

Mas existe outro cenário.

O próprio z/OS pode precisar chamar APIs externas.

Imagine um programa COBOL processando uma transação de cartão.

Ele precisa consultar um sistema antifraude baseado em IA rodando em cloud.

Fluxo:

CICS
 |
 v
COBOL
 |
 v
Integração API
 |
 v
Serviço antifraude
 |
 v
Cloud

Pergunta:

Mainframe pode consumir APIs modernas?

Sim.

Isso quebra uma imagem antiga do mainframe como uma fortaleza completamente isolada.

Na realidade, ambientes modernos são híbridos.

Algo como:

                CLOUD

         +------------------+
         | Fraud Detection  |
         +--------+---------+
                  ^
                  |
                REST
                  |
                  |
+----------------------------------+
|              IBM Z               |
|                                  |
|     COBOL ---- z/OS Connect      |
|       |                          |
|      CICS                        |
|       |                          |
|      Db2                         |
+----------------------------------+

Isso permite ao legado participar de ecossistemas modernos sem abandonar tudo aquilo que já faz bem.

---

Um pequeno caso para Watson investigar

Imagine uma transferência bancária.

O fluxo COBOL tradicional:

1. Validar conta de origem
2. Validar conta destino
3. Verificar saldo
4. Verificar limite
5. Executar débito
6. Executar crédito
7. Registrar auditoria

Agora surge uma nova regra:

Consultar sistema externo antifraude.

O programa pode enviar dados como:

{
  "customer": "823718",
  "amount": 12500.00,
  "destination": "998812",
  "channel": "MOBILE"
}

e receber:

{
  "riskScore": 87,
  "decision": "REVIEW"
}

O COBOL pode então continuar seu processamento.

Note o fenômeno.

O sistema não foi substituído.

Ele foi enriquecido por integração.

---

Segurança: Moriarty encontra a API

Toda vez que você cria uma nova interface, cria também uma nova superfície de ataque.

Moriarty ficaria muito interessado.

Imagine esta API:

POST /payments

Excelente.

Agora imagine que qualquer pessoa possa chamá-la.

Péssimo.

Logo entram conceitos como:

TLS
OAuth
JWT
autenticação
autorização
identidade
RACF
logging
auditoria
políticas

Uma arquitetura simplificada:

Aplicação
   |
   | token
   v
API Gateway
   |
   v
z/OS Connect
   |
   v
Segurança z/OS
   |
   v
CICS
   |
   v
COBOL

A pergunta crítica deixa de ser apenas:

“A API funciona?”

e passa a incluir:

“Quem chamou?”

“Com qual identidade?”

“Qual recurso tentou acessar?”

“Estava autorizado?”

“O que foi executado?”

“Existe trilha de auditoria?”

Para quem já conhece RACF, a filosofia não é estranha.

RACF sempre quis saber:

USER
RESOURCE
ACCESS

APIs simplesmente ampliam esse problema para um novo universo.

---

Easter egg nº 2: Sherlock provavelmente seria sysprog

Holmes observa detalhes insignificantes para inferir causas complexas.

Um sysprog vê:

IEC141I

e começa a reconstruir mentalmente meia hora de atividade no sistema.

Watson vê apenas:

“Deu erro.”

Holmes vê:

dataset, volume, catalog, disposition, job, step, allocation, contexto.

A diferença entre novato e veterano frequentemente não é conhecer mais comandos.

É reconhecer padrões.

Sherlock Holmes seria absolutamente perigoso com acesso ao SDSF.

---

A armadilha do “REST em tudo”

Agora vem um dos pontos mais importantes.

APIs são ferramentas.

Não religião.

Imagine um batch processando:

10.000.000 registros

localmente.

Alguém decide modernizar:

Cada registro chamará uma REST API.

Então você substitui:

10 milhões de operações locais

por:

10 milhões de chamadas HTTP.

Agora adicionamos:

rede
TLS
serialização
desserialização
timeouts
retries
latência
conexões
rate limits
monitoramento distribuído

Watson exclama:

— Mas ficou moderno!

Holmes responde:

— E quarenta vezes mais lento.

Nem toda chamada deve virar API.

Existem cenários em que:

CALL
LINK
MQ
batch
arquivo
Db2

continuam sendo alternativas perfeitamente adequadas.

Arquitetura madura não pergunta:

“Qual tecnologia está na moda?”

Ela pergunta:

“Qual mecanismo resolve melhor este problema?”

---

Granularidade: o caso das 47 APIs

Imagine um aplicativo bancário mostrando a página inicial.

Ele precisa de:

nome
saldo
limite
cartões
investimentos
últimas transações
empréstimos
mensagens

O arquiteto mais empolgado cria:

GET /customer
GET /balance
GET /limit
GET /cards
GET /investments
GET /transaction1
GET /transaction2
GET /transaction3
GET /loan
GET /messages

A tela abre.

E dispara uma pequena invasão contra o próprio mainframe.

Mobile
 |
 |--> API
 |--> API
 |--> API
 |--> API
 |--> API
 |--> API
 |--> API
 |--> API
 |
 v
z/OS

Isso pode gerar problemas de:

• volume;

• latência;

• CPU;

• conexão;

• dependências;

• falhas parciais;

• escalabilidade.

Holmes diria:

“O fato de haver quarenta pegadas não significa que quarenta pessoas passaram pela sala. Talvez Watson tenha caminhado em círculos.”

Em APIs também.

Precisamos analisar granularidade.

Talvez a tela precise de uma API agregadora:

GET /customer-home

que retorne várias informações em uma chamada.

Não existe resposta universal.

Existe engenharia.

---

Observabilidade: onde estão escondidos os 4 segundos?

No velho ambiente:

CICS
 |
COBOL
 |
Db2

Se algo demorava, você analisava:

CICS statistics
SMF
RMF
Db2
CPU
I/O
locks
waits

Agora temos:

Smartphone
    |
Internet
    |
API Gateway
    |
z/OS Connect
    |
CICS
    |
COBOL
    |
Db2

Usuário reclama:

“Consulta demorou quatro segundos.”

Watson aponta para COBOL.

Holmes pergunta:

— Por quê?

— Porque é legado.

— Evidência?

— Nenhuma.

Então começa a investigação.

Talvez:

Mobile             150 ms
Internet           420 ms
Gateway             30 ms
z/OS Connect        40 ms
CICS                 4 ms
COBOL                7 ms
Db2                  5 ms
serviço externo   3100 ms

Resultado:

COBOL estava inocente.

Esse tipo de ambiente exige observabilidade ponta a ponta.

Você precisa conseguir seguir a transação desde a origem até o backend.

---

Kubernetes entra pela janela

Agora podemos ligar z/OS Connect ao mundo cloud-native.

Imagine:

+--------------------------------+
| Kubernetes                     |
|                                |
| Pod                            |
|   Spring Boot                  |
|                                |
+-------------+------------------+
              |
              | REST
              v
        z/OS Connect
              |
              v
            CICS
              |
              v
            COBOL
              |
              v
             Db2

Isso não é contradição.

É arquitetura híbrida.

Durante anos venderam uma falsa escolha:

MAINFRAME OU CLOUD

Na prática, muitas organizações operam:

MAINFRAME E CLOUD.

Cada plataforma resolve determinado conjunto de problemas.

Kubernetes pode executar:

frontends
microsserviços
APIs
workers
integrações
serviços stateless

IBM Z pode continuar executando:

core banking
pagamentos
contabilidade
CICS
IMS
Db2
batch crítico
regras centrais

APIs conectam os dois universos.

---

O mistério dos microsserviços

Watson encontra uma API REST.

— Holmes! Descobri um microsserviço!

Holmes olha para o backend:

REST
 |
 v
z/OS Connect
 |
 v
Programa COBOL de 400 mil linhas

— Não, Watson.

REST não significa automaticamente microsserviço.

Um monólito pode expor APIs.

Um microsserviço pode nem sequer usar REST.

Arquitetura de microsserviços envolve características como:

• autonomia;

• limites funcionais;

• implantação independente;

• ownership;

• domínio;

• resiliência;

• governança distribuída.

Colocar:

/api

na frente de uma aplicação não transforma automaticamente sua arquitetura.

E isso nem sempre é problema.

Monólitos bem estruturados podem ser excelentes.

A pergunta deveria ser:

O sistema atende adequadamente os requisitos?

Não:

Ele parece suficientemente moderno numa apresentação?

---

Passo a passo mental para estudar z/OS Connect

Agora vamos montar o nosso roteiro de investigador.

Sempre que você olhar uma arquitetura, comece identificando cinco personagens.

1. Quem chama?

Pode ser:

Mobile
Web
Java
Python
Node.js
Kubernetes
Parceiro
SaaS
COBOL

Esse é o consumer.

---

2. Qual é a API?

Pergunte:

Qual endpoint?
Qual método?
Qual request?
Qual response?
Qual autenticação?

Exemplo:

GET /accounts/{id}/balance

---

3. Quem executa a regra real?

Pode ser:

CICS
IMS
COBOL
Db2
outra aplicação z/OS

Esse é o backend.

---

4. Como os dados são transformados?

Exemplo:

JSON
 |
 v
accountId = "123456"
 |
 v
estrutura COBOL
 |
 v
PIC 9(06)

E no retorno:

COMP-3
 |
 v
transformação
 |
 v
JSON number

---

5. Como a identidade atravessa o caminho?

Pergunte:

Quem é o usuário?
Qual token?
Qual credencial?
Como chega ao z/OS?
Qual autorização existe?

---

6. Como diagnostico problemas?

Pergunte:

Onde vejo logs?
Como correlaciono chamadas?
Como meço latência?
Como encontro falhas?
Como identifico backend lento?

Se você consegue responder essas seis perguntas, já deixou de apenas “usar uma ferramenta”.

Começou a entender arquitetura.

---

Exemplo completo: o caso da conta desaparecida

Recebemos uma chamada:

GET /accounts/123456/balance

O consumidor espera:

{
  "balance": 4200.75
}

Fluxo:

Mobile
 |
 v
API Gateway
 |
 v
z/OS Connect
 |
 v
CICS transaction
 |
 v
COBOL
 |
 v
Db2

COBOL executa:

EXEC SQL
   SELECT BALANCE
     INTO :WS-BALANCE
     FROM ACCOUNT
    WHERE ACCOUNT_ID = :WS-ACCOUNT-ID
END-EXEC.

Agora imagine:

SQLCODE = +100

Não encontrado.

No velho mundo, talvez você apresentasse:

ACCOUNT NOT FOUND

No mundo HTTP, podemos mapear semanticamente para:

HTTP 404

com:

{
  "error": "ACCOUNT_NOT_FOUND"
}

Observe novamente a tradução de paradigmas.

Db2 fala:

SQLCODE +100

CICS/COBOL entende sua lógica.

HTTP fala:

404

O consumidor moderno entende JSON.

O papel da arquitetura é fazer esses mundos conversarem sem destruir as características de cada um.

---

Curiosidade: interfaces mudam muito mais rápido que regras de negócio

Isso explica por que sistemas legados permanecem durante décadas.

Imagine uma regra:

SE SALDO + LIMITE >= VALOR
   AUTORIZAR TRANSAÇÃO

Ela pode existir desde 1995.

Enquanto a interface já passou por:

terminal
cliente-servidor
web
SOAP
mobile
REST
app
cloud

A regra mudou pouco.

A interface mudou seis vezes.

Isso explica uma ideia importantíssima em arquitetura:

isole aquilo que muda daquilo que permanece.

z/OS Connect ajuda justamente a separar:

regra central

de:

forma de acesso.

---

O antipadrão mais perigoso: API arqueológica

Imagine simplesmente pegar todas as transações antigas e expô-las diretamente:

TRN1 -> /trn1
TRN2 -> /trn2
TRN3 -> /trn3
TRN4 -> /trn4

Tecnicamente funciona.

Arquiteturalmente talvez seja um desastre.

Uma API deveria representar conceitos compreensíveis para consumidores.

Prefira coisas como:

/accounts
/customers
/payments
/cards

em vez de simplesmente publicar detalhes internos do CICS.

Porque se a API refletir profundamente a implementação interna, você cria acoplamento.

E então a suposta modernização apenas colocou JSON sobre a arquitetura antiga.

Holmes chamaria isso de:

o velho suspeito usando bigode falso.

---

Performance não desaparece porque usamos JSON

Outro erro comum é imaginar que APIs tornam performance um problema “do middleware”.

Não.

Cada request possui custo.

Podemos imaginar:

tempo total =
rede
+ TLS
+ gateway
+ processamento z/OS Connect
+ chamada CICS
+ execução COBOL
+ Db2
+ serialização
+ retorno

Se sua aplicação gerar:

20 requests

para cada usuário, e houver:

100.000 usuários simultâneos

a matemática rapidamente fica interessante.

Portanto, pense sempre em:

TPS
latência
concorrência
payload
CPU
conexões
timeouts
retries

O famoso velho mainframe continua cobrando aluguel por ciclo de CPU. 😄

---

Retry: o pequeno detalhe que pode duplicar dinheiro

Imagine:

POST /payments

O cliente envia uma transferência.

O backend processa.

Mas a resposta HTTP se perde.

O consumidor pensa:

Não funcionou.

Então faz retry.

Se o design não for cuidadoso, você pode executar a transferência duas vezes.

Por isso APIs transacionais precisam pensar em conceitos como:

idempotência
transaction IDs
correlation IDs
controle de duplicidade

Exemplo:

X-Transaction-ID: ABC123XYZ

O backend pode registrar:

ABC123XYZ já processada.

Isso é um excelente exemplo de como integração aparentemente simples toca profundamente em engenharia transacional.

O programador CICS veterano provavelmente sorrirá:

“Vocês acabaram de redescobrir problemas que resolvemos há quarenta anos.”

Sim.

Cloud-native frequentemente descobre que o velho mainframe já conhecia alguns monstros.

Apenas lhes dava outros nomes.

---

Easter egg nº 3: “Elementary, my dear Watson”

A frase mais associada a Sherlock Holmes:

“Elementary, my dear Watson.”

Curiosamente não aparece exatamente dessa forma nos contos originais de Arthur Conan Doyle.

É uma construção popularizada posteriormente.

Isso combina perfeitamente com tecnologia.

Várias “verdades históricas” de TI também se repetem até parecerem fatos:

Mainframe vai acabar.

COBOL vai desaparecer.

Batch é ultrapassado.

Tudo será cloud.

Tudo será microsserviço.

Décadas passam.

O mainframe continua processando.

COBOL continua executando.

Batch continua fechando o dia.

E alguém coloca Kubernetes na frente de tudo.

---

z/OS Connect como tradutor entre gerações

Talvez esta seja a melhor forma de compreender a tecnologia.

Imagine três gerações.

Geração 1

3270
CICS
COBOL
VSAM
Db2

Geração 2

Java
Web
SOAP
Application Servers

Geração 3

REST
JSON
OpenAPI
Cloud
Kubernetes
Mobile

Uma empresa raramente substitui uma geração inteira pela seguinte.

Ela acumula camadas.

Logo temos:

Mobile
   |
Cloud
   |
REST
   |
z/OS Connect
   |
CICS
   |
COBOL
   |
Db2

E isso não é necessariamente feio.

Pode ser exatamente a arquitetura apropriada.

---

A grande lição para o programador COBOL iniciante

Se você está começando agora em COBOL, existe uma tentação perigosa.

Pensar:

Preciso aprender apenas COBOL.

Não.

Aprenda COBOL profundamente.

Mas aprenda também o mundo ao redor.

Entenda:

HTTP
REST
JSON
OpenAPI
APIs
TLS
OAuth
JWT
CICS
Db2
MQ
Git
CI/CD
containers
Kubernetes

Você não precisa se transformar em especialista em tudo.

Mas precisa entender como essas peças se encaixam.

Porque o profissional COBOL mais valioso não será necessariamente aquele que memoriza mais verbos da linguagem.

Será aquele que consegue olhar:

React
 |
API
 |
z/OS Connect
 |
CICS
 |
COBOL
 |
Db2

e compreender a transação inteira.

Esse profissional consegue conversar com:

dev web
arquiteto
sysprog
DBA
segurança
cloud
CICS admin
negócio

Ele se torna uma ponte humana entre tecnologias.

E pontes são valiosas quando existem dois mundos que precisam conversar.

---

O último diálogo em Baker Street

Watson fecha o notebook.

— Então conseguimos transformar nosso sistema COBOL em um sistema moderno?

Holmes balança a cabeça.

— Não exatamente.

— Não?

— O sistema já era moderno para o problema que resolvia.

Watson franze a testa.

Holmes continua:

— Apenas ensinamos o resto do mundo a conversar com ele.

No monitor aparece:

GET /accounts/123456/balance

A chamada atravessa HTTPS.

Passa pela camada de APIs.

Chega ao z/OS Connect.

Entra no CICS.

Executa COBOL.

Consulta Db2.

Volta.

{
  "balance": 7250.00
}

O smartphone exibe:

Saldo disponível: R$ 7.250,00

Em algum lugar abaixo de milhares de camadas de software, um programa COBOL executa:

MOVE WS-SALDO TO CA-SALDO.

Ninguém no celular sabe.

Ninguém precisa saber.

Holmes sorri.

— Elementary, Watson.

— O quê?

— Modernização não significa demolir a mansão.

Holmes aponta para a tela.

— Às vezes basta instalar uma porta nova.

E talvez essa seja a melhor definição informal de z/OS Connect para quem vem do mundo COBOL:

uma porta moderna instalada em uma casa que continua sendo extraordinariamente boa em guardar as coisas mais valiosas da empresa.

No mundo do Bellacosa Mainframe, Watson finalmente aprende a regra:

LEGADO + API != LEGADO DISFARÇADO

LEGADO + BOA ARQUITETURA
        =
CAPACIDADE REUTILIZADA

E quando algum consultor aparecer dizendo:

“Precisamos reescrever tudo.”

Não discuta.

Pegue a lupa.

Pergunte:

Qual é o problema real?

É a regra?

É a plataforma?

É a interface?

É a integração?

É performance?

É custo?

É competência?

Ou alguém simplesmente confundiu
idade com obsolescência?

Sherlock Holmes aprovaria.

O velho sysprog também.

E o COBOL?

O COBOL continuará rodando enquanto todos terminam a reunião.

☕🔎🖥️