Bellacosa Mainframe e o cobol falando com a web via api

☕ Um Café no Bellacosa Mainframe

Dr. Watson Entra no CICS — O Caso do COBOL que Não Sabia que Era uma API

Ou: por que o programa que calcula a folha há trinta anos pode conversar com um aplicativo no celular sem trocar de linguagem, trocar de cérebro ou colocar bigode no JSON

“Holmes”, perguntou o Dr. Watson, olhando para o monitor onde um aplicativo de celular acabara de consultar o saldo de uma conta, “então o COBOL finalmente aprendeu Java?”

Sherlock nem levantou os olhos do log de uma transação CICS.

“Não, Watson. E esta é justamente a dedução que separa um arquiteto de alguém que instala uma biblioteca, desenha três setas num PowerPoint e chama a reunião de modernização.”

O espanto do Watson é o de muita gente, inclusive de bons desenvolvedores iniciantes. Eles ouvem “aplicação moderna”, pensam em React, Java, Python, Kubernetes, cloud, aplicativo de celular e JSON. Depois ouvem “COBOL”, imaginam uma sala empoeirada, cartões perfurados e um sistema incapaz de conversar com qualquer coisa que tenha tela sensível ao toque.

É uma imagem divertida, mas errada.

COBOL não precisa “virar Java” para participar do mundo digital. O que ele precisa é de uma porta de entrada bem desenhada, de um contrato claro para trocar dados e de uma camada que traduza a conversa entre os dois mundos. O COBOL continua realizando aquilo que sabe fazer muito bem: aplicar regras de negócio, consultar Db2, ler VSAM, conversar com IMS, validar limites, calcular valores e manter a consistência de uma operação que não pode falhar porque alguém colocou um emoji no campo de observação.

Neste café, Watson será nosso cronista. Ele vai acompanhar a investigação desde o primeiro JSON até o retorno da resposta, descobrir por que um campo aparentemente inocente pode produzir um erro enorme e perceber que modernizar não é demolir a agência bancária para instalar uma máquina de café expresso.

1. A primeira pista: ninguém “fala COBOL” pela internet

Quando um aplicativo mobile pede uma segunda via de boleto ou verifica a margem consignável de um cliente, ele normalmente envia uma requisição HTTP ou HTTPS. HTTP é o protocolo da conversa; HTTPS é essa conversa protegida por TLS. JSON é o formato textual usado para organizar os dados.

Uma solicitação simples poderia ser:

{
  "employeeId": "10025",
  "requestType": "PAYROLL"
}

O aplicativo não está chamando diretamente um PERFORM dentro de um programa COBOL. Ele está chamando uma API, algo como:

POST /payroll/v1/employee-query

O endpoint recebe a chamada, identifica o consumidor, valida a entrada e encaminha os dados para o ativo de negócio correto no z/OS. Esse ativo pode ser um programa COBOL sob CICS, uma transação IMS, uma rotina que consulta Db2 ou até uma composição de serviços.

O ponto decisivo é este: linguagem não é protocolo. Java, .NET, Python e COBOL podem participar da mesma conversa porque todos entendem os acordos de integração: rede, segurança, formatos e contratos. O programa COBOL não precisa entender a moda do framework da semana; a camada de serviço se encarrega de apresentar uma interface estável ao exterior.

Watson anotou: “Portanto, o celular não invade o mainframe; ele toca a campainha certa.” Exatamente.

2. A cena do crime: o caminho real da chamada

O desenho simplificado “COBOL → CICS → HTTP → JSON → aplicação moderna” transmite a ideia geral, mas na vida real as responsabilidades precisam aparecer. Um fluxo comum se parece mais com isto:

Aplicativo mobile / portal / serviço cloud
             |
        HTTPS + JSON
             |
API Gateway e camada de segurança
             |
z/OS Connect, CICS Web API ou serviço CICS
             |
COMMAREA, CHANNEL/CONTAINER, MQ ou chamada de programa
             |
Programa COBOL
             |
Db2, VSAM, IMS, MQ e regras de negócio

Nem toda empresa usa exatamente todos esses blocos. Em algumas, o CICS recebe HTTP diretamente. Em outras, o z/OS Connect expõe uma API REST sobre ativos CICS e IMS. Em outras, uma camada Java no z/OS ou numa plataforma distribuída faz parte da composição. E, quando o processo não exige resposta imediata, IBM MQ pode ser mais apropriado do que manter uma chamada HTTP esperando.

O erro de principiante é tratar todas essas opções como rivais. Elas são ferramentas para problemas diferentes.

• Uma consulta de saldo tende a ser síncrona: pergunta, processa, responde.

• Um pedido de recálculo de folha de milhões de pessoas pode ser assíncrono: recebe a solicitação, coloca trabalho em fila, processa com controle e devolve um protocolo.

• Uma integração antiga pode continuar usando SOAP e XML; uma nova pode preferir REST e JSON.

Não existe medalha para quem força tudo a virar API síncrona. Há apenas incidentes mais elegantes.

3. CICS: o recepcionista que não deixa o visitante chegar à sala-cofre

Para quem começa em COBOL, CICS pode parecer apenas aquele ambiente onde aparecem comandos EXEC CICS. Mas, nesta história, ele é muito mais: é um gerenciador de transações, recursos, segurança e execução online.

Pense no programa COBOL como o especialista que conhece a regra da folha. Ele não deveria receber uma ligação de qualquer pessoa, a qualquer hora, com campos sem validação e a ordem “faz aí”. CICS organiza a entrada, executa a transação sob controle, protege recursos, ajuda a lidar com concorrência e fornece mecanismos para a aplicação funcionar online com previsibilidade.

Quando a integração é feita adequadamente, o serviço não expõe necessariamente o programa legado inteiro. Ele expõe uma capacidade de negócio. Em vez de criar uma API chamada:

EXECUTA-PGM-PG1234-COM-AREA-DE-327-BYTES

você cria:

GET /customers/{id}/payroll-summary

O primeiro nome descreve o porão da casa. O segundo descreve o serviço que a empresa oferece. A diferença parece estética até o dia em que muda o programa interno e cinquenta consumidores externos não deveriam nem perceber.

4. O tradutor entre JSON e COBOL

Aqui está o ponto onde Watson encontra a lupa no chão.

JSON é flexível. Um campo pode vir ou não vir. Um valor pode chegar como texto, número, lista ou objeto. O formato é legível, usa UTF-8 e costuma carregar nomes expressivos.

COBOL, em contrapartida, gosta de estruturas definidas, tamanhos conhecidos e tipos declarados. Um identificador pode ser PIC X(5); uma data pode ter oito posições; um valor monetário pode ser PIC S9(7)V99 COMP-3. Isso não é uma deficiência. É parte da previsibilidade que tornou esses sistemas valiosos.

Uma representação de trabalho para a entrada poderia ser:

01  WS-PAYROLL-REQUEST.
    05  WS-EMPLOYEE-ID       PIC X(5).
    05  WS-REQUEST-TYPE      PIC X(10).

E a saída:

01  WS-PAYROLL-RESPONSE.
    05  WS-STATUS            PIC X(10).
    05  WS-EMPLOYEE-ID       PIC X(5).
    05  WS-EMPLOYEE-NAME     PIC X(40).
    05  WS-SALARY            PIC S9(7)V99 COMP-3.

Uma camada de transformação recebe o JSON, aplica regras de mapeamento e fornece ao COBOL uma estrutura coerente. Na volta, converte o resultado para JSON:

{
  "status": "SUCCESS",
  "employeeId": "10025",
  "employeeName": "JOHN",
  "salary": 4500.00
}

O jovem padawan, hipnotizado pelo exemplo, talvez diga: “Então basta copiar os campos”. Watson, que já viu Holmes derrubar uma tese inteira por causa de uma cinza de charuto, deve desconfiar. Copiar campos é a parte fácil. Definir a semântica correta é o trabalho de verdade.

5. As cinco armadilhas escondidas no JSON

Identificador não é quantidade

O valor "00025" pode ser um código, não o número vinte e cinco. Se o aplicativo moderno o transforma em 25, os zeros à esquerda desaparecem. Para o COBOL e para a regra de negócio, isso pode apontar para outro registro ou simplesmente não encontrar nenhum.

Quando o dado representa identidade — conta, agência, matrícula, CPF formatado, código de produto — trate-o como texto, mesmo que visualmente só tenha dígitos.

Dinheiro não gosta de improviso

No Brasil, um usuário pode escrever 4500,00; JSON numérico usa ponto: 4500.00. Um valor monetário também não deve passar por conversões descuidadas de ponto flutuante. O desenho precisa definir precisão, arredondamento, moeda e comportamento para valores ausentes.

O campo COBOL S9(7)V99 COMP-3 é eficiente internamente, mas não deve “vazar” para o contrato. Externamente, o consumidor precisa de um número JSON ou, em situações que exijam controle absoluto de precisão, de uma convenção bem documentada.

Ausente, nulo, branco e zero são quatro pessoas diferentes

No JSON, um campo pode estar ausente, pode ser null, pode ser string vazia ou pode ser zero. No COBOL, dependendo do mapeamento, tudo isso pode acabar como espaços ou zeros. Se a API não define o comportamento, alguém poderá sem querer alterar um limite para zero ou apagar uma informação válida.

Datas são pequenas bombas-relógio

Defina um padrão externo, normalmente YYYY-MM-DD ou data-hora ISO 8601 com fuso. Nunca deixe cada consumidor decidir se 03/04/2026 significa 3 de abril ou 4 de março. O COBOL pode trabalhar internamente com outro layout, desde que a conversão seja centralizada e testada.

UTF-8, EBCDIC e o acento que virou evidência

O mundo web normalmente trafega UTF-8. O z/OS historicamente trabalha com EBCDIC em muitas áreas. Ferramentas e camadas modernas realizam conversões, mas o time precisa testar nomes com acentos, cedilha, caracteres especiais e limites de tamanho. “João D’Ávila” é um teste melhor do que “JOHN”.

Easter egg do caso: o primeiro incidente muitas vezes não aparece com um número errado. Ele aparece quando “AÇÃO PROMOCIONAL” se transforma em um texto esquisito no extrato e alguém descobre que o ambiente de teste só possuía clientes chamados ANA e JOSE.

6. REST, SOAP, MQ e o falso campeonato de tecnologias

REST com JSON é muito popular porque é simples de consumir por apps web e mobile. SOAP com XML ainda existe em muitas empresas e pode ser adequado em integrações formais já consolidadas. IBM MQ é excelente quando confiabilidade, desacoplamento e processamento assíncrono são mais importantes do que uma resposta imediata.

Veja a escolha pela pergunta de negócio, não pela propaganda:

Caso	Opção frequentemente adequada
Consultar saldo ou status	API REST síncrona
Integrar serviço corporativo antigo	SOAP/XML, se o contrato já existe
Enviar lote, evento ou comando crítico	IBM MQ
Publicar função CICS/IMS para apps digitais	z/OS Connect ou recurso CICS
Fazer o COBOL consumir serviço externo	Cliente HTTP, integração CICS ou camada intermediária

Watson perguntou se REST “substitui” MQ. Holmes respondeu que uma chave inglesa não substitui um extintor. As duas coisas são importantes; apenas não devem ser usadas no mesmo parafuso.

7. A regra de ouro: exponha capacidade, não a anatomia do legado

Um erro comum de modernização é publicar uma API que reproduz o layout interno da COMMAREA, inclusive nomes históricos, campos reservados e indicadores sem significado para o consumidor.

Uma API fraca poderia devolver:

{
  "ws-ind-op": "A",
  "filler-01": "",
  "vlr-pgm": "00000450000",
  "ind-erro": "00"
}

Uma API saudável devolve algo que representa o domínio:

{
  "employeeId": "10025",
  "monthlySalary": 4500.00,
  "currency": "BRL",
  "processingStatus": "COMPLETED"
}

Isso permite modernizar por camadas. Por trás da API, você pode reorganizar programas, substituir um acesso, adicionar validações ou migrar uma parte do fluxo. Se o contrato público continuar compatível, o aplicativo consumidor não precisa saber da cirurgia interna.

É o princípio do strangler pattern: em vez de demolir um sistema inteiro num fim de semana heroico — geralmente seguido de uma segunda-feira traumática — a empresa cerca, substitui ou reorganiza partes aos poucos, mantendo o negócio funcionando.

8. Segurança: a porta moderna precisa ser mais forte, não mais aberta

Expor um serviço de mainframe não significa colocar uma transação CICS diretamente na internet e confiar no bom coração dos robôs. Uma arquitetura séria inclui autenticação, autorização, TLS, rate limiting, auditoria e mascaramento de dados.

Uma resposta para um app não deve devolver ASRA, S0C7, SQLCODE -805 ou o nome da tabela interna. Essas informações são valiosas para diagnóstico, mas péssimas como interface externa e potencialmente úteis para um atacante.

Em vez disso:

{
  "status": "ERROR",
  "code": "EMPLOYEE_NOT_FOUND",
  "message": "Employee was not found."
}

Do lado interno, a equipe mantém o detalhe: correlation ID, usuário técnico, horário, URI, transação CICS, programa chamado, SQLCODE e logs de segurança. Um bom correlation ID é a etiqueta de bagagem da transação: ele permite seguir a mesma solicitação do celular até o programa COBOL, passando pelo gateway e pelo CICS.

Também vale a dica de Watson para qualquer iniciante: não coloque segredo no código. Senhas, tokens, certificados e chaves de API precisam de gestão apropriada, rotação e controle de acesso. Um segredo em fonte COBOL é apenas um incidente aguardando o próximo upload ou print de tela.

9. Passo a passo: como transformar uma regra COBOL em serviço

Vamos supor que a empresa quer publicar a consulta resumida de folha de um funcionário.

1. Descubra a capacidade de negócio. Não comece pelo programa. Comece pela pergunta: “o que o canal digital precisa saber?”. Aqui: consultar o resumo de folha de um funcionário autorizado.

2. Mapeie a regra existente. Qual programa COBOL calcula ou consulta o dado? Ele recebe COMMAREA? Usa CHANNEL/CONTAINER? Chama outros módulos? Consulta Db2, VSAM ou IMS? Possui efeitos colaterais?

3. Defina o contrato da API. Nome, URI, método HTTP, campos obrigatórios, tipos, respostas, erros, versão e exemplos. Um contrato bem escrito é uma peça de engenharia, não burocracia.

4. Crie uma camada adaptadora se necessário. O programa antigo não precisa ser mutilado para ficar bonito para a API. Um programa ou serviço adaptador pode receber a estrutura externa, validar, chamar a regra existente e montar a resposta.

5. Implemente o mapeamento. Decida como cada campo JSON vira uma variável COBOL e como cada resultado vira JSON. Documente regras de nulo, espaços, zeros, datas, arredondamento e caracteres.

6. Proteja a entrada. Autentique o cliente, autorize a operação, valide tamanhos e conteúdo. Não deixe um campo de 40 caracteres cair numa área de 10 porque “em homologação funcionou”.

7. Teste o caminho feliz e o caminho humano. O caminho feliz é funcionário existente, valor válido e infraestrutura saudável. O caminho humano inclui ID inexistente, requisição duplicada, JSON malformado, campo ausente, timeout, Db2 indisponível, acesso não autorizado e caracteres especiais.

8. Observe a operação. Inclua logs, métricas, traces e correlation ID. Uma API que funciona só quando alguém está olhando o console não está pronta para produção.

9. Publique sem quebrar consumidores. Se a versão 1 está em uso, não renomeie um campo de uma hora para outra. Versione, mantenha compatibilidade durante a transição e avise quem consome.

10. Meça o resultado. Tempo de resposta, volume, erros por tipo, picos, dependências e impacto no CICS/Db2. Modernização sem observabilidade é apenas uma aposta com interface bonita.

10. O que o COBOL iniciante deve aprender primeiro

Você não precisa dominar todos os produtos antes de entender a arquitetura. Comece construindo o mapa mental:

• um programa COBOL recebe dados e devolve dados;

• CICS coordena muitos programas online e protege a transação;

• COMMAREA e CHANNEL/CONTAINER são formas de passar dados entre componentes CICS;

• Db2, VSAM e IMS são fontes comuns de dados e regras;

• HTTP/HTTPS levam a chamada;

• JSON é o envelope legível pelo aplicativo moderno;

• uma API estabelece contrato, segurança e governança.

Depois, pratique separação de responsabilidades. Faça um programa COBOL que receba uma estrutura simples, valide um identificador, consulte um dado fictício ou Db2 de laboratório e devolva códigos de retorno claros. Em seguida, imagine como ele seria chamado por uma API. O salto mental mais importante não é decorar cada comando: é aprender a distinguir interface externa, regra de negócio e acesso a dados.

Epílogo — A conclusão de Watson

No fim do caso, o Dr. Watson fechou o caderno.

“Então o COBOL não está sobrevivendo apesar do mundo moderno. Ele pode participar dele porque sua regra continua útil — desde que alguém construa a ponte corretamente.”

Holmes assentiu.

“Precisamente. A tecnologia nova não apaga a necessidade de uma regra correta. Apenas aumenta a velocidade com que uma regra errada consegue chegar ao celular de milhões de pessoas.”

Essa é a grande lição. Modernizar COBOL não significa transformar todo programa em moda tecnológica nem tratar o mainframe como peça de museu. Significa criar integrações bem projetadas, seguras, observáveis e com contratos claros, preservando o que já funciona e mudando aquilo que precisa mudar.

O celular pode ter uma tela brilhante. O gateway pode estar na cloud. A resposta pode vir em JSON. Mas, no coração do processo, pode continuar existindo um programa COBOL que conhece a regra, protege o dado e não se impressiona com o último framework lançado numa sexta-feira.

E, quando a transação precisa fechar corretamente, Watson, é melhor que ele não se impressione mesmo.