☕ Um Café no Bellacosa Mainframe
Gostou do conteúdo? Ajude a manter o café quente, o COBOL compilando e o mainframe acordado. 😄
☕ Pague um café ao Bellacosa

Translate

Mostrar mensagens com a etiqueta CCSID. Mostrar todas as mensagens
Mostrar mensagens com a etiqueta CCSID. Mostrar todas as mensagens

quarta-feira, 4 de novembro de 2026

🗿A Pedra de Roseta de Thoth no IBM Z: EBCDIC, UTF-8, CCSID e Conversão de Dados COBOL/Java

 

Bellacosa Mainframe e os problemas de tabelas de caracteres

☕ UM CAFÉ NO BELLACOSA MAINFRAME

🗿 A PEDRA DE ROSETA DE THOTH NO IBM Z: QUANDO EBCDIC, UTF-8 E UNICODE TENTAM TRADUZIR O MESMO NOME — CCSID 037, 1047, 1208, JAVA, JSON E A IDENTIDADE QUE DESAPARECEU ENTRE OS BYTES!

São 03h17. Um programa COBOL envia uma transferência de R$ 1,25 bilhão para uma aplicação Java. O CICS confirma a comunicação, o Db2 registra a operação e a API responde HTTP 200. Mas o nome do beneficiário sofreu uma transformação: João Gonçalves tornou-se um conjunto de caracteres estranhos. O dinheiro não desapareceu, porém a identidade digital do destinatário deixou de corresponder à informação original. Uma investigação sobre EBCDIC, Unicode, UTF-8, CCSIDs, páginas de código, normalização de caracteres, JSON, APIs e o perigo de uma conversão tecnicamente bem-sucedida que modifica o significado dos dados.


🎬 Prólogo — 03h17: o homem que entrou como João e saiu como outra pessoa

São Paulo, 19 de novembro de 2026.

03h17.

O Banco de Mênfis está realizando uma transferência especial.

Valor: R$ 1.250.000.000,00.

Beneficiário: João Gonçalves.

A solicitação chega a uma transação CICS executada no IBM Z.

O programa COBOL valida os dados.

O Db2 registra a operação conforme o fluxo autorizado.

Um channel CICS transporta as informações para um programa Java.

A aplicação Java prepara a resposta JSON.

O serviço informa que a solicitação foi processada.

O gerente observa:

— Tudo funcionando!

Mas o analista de integração aponta para o relatório.

— Temos um problema no nome do beneficiário.

O cadastro original apresenta:

JOÃO GONÇALVES

A resposta de um componente apresenta:

JOÃO GONÇALVES

O gerente fica perplexo.

— Que cliente é esse?

— É o mesmo identificador de operação. Mas o campo de nome foi interpretado incorretamente em alguma etapa.

— O Db2 corrompeu o registro?

— Ainda não sabemos.

— Foi o Java?

— Também não podemos concluir isso sem examinar os bytes.

— Mas o CICS retornou sucesso!

O veterano aproxima-se.

— Isso comprova determinados aspectos da execução. Não prova que todas as conversões de caracteres preservaram a informação original.

Ele abre um livro de arqueologia.

Na página aparece a famosa Pedra de Roseta.

— Senhores, precisamos aprender a traduzir os escritos de Thoth.

O gerente suspira.

— Outra aventura egípcia?

— Esta talvez seja uma das mais importantes. Porque não estamos investigando dinheiro desaparecido, e sim a identidade de quem deveria recebê-lo.

No quadro, o veterano escreve:

CARACTERE ≠ BYTE ≠ CODIFICAÇÃO ≠ SIGNIFICADO EMPRESARIAL.

E a investigação começa.



🏺 Capítulo I — A Pedra de Roseta: quando três escritas abriram as portas de uma civilização

A Pedra de Roseta é um dos objetos mais famosos da história da arqueologia e da linguística.

Encontrada em 1799 durante a campanha francesa no Egito, tornou-se uma peça essencial no processo de decifração dos hieróglifos egípcios.

O monumento contém um decreto promulgado em 196 a.C., durante o reinado de Ptolomeu V.

O texto aparece em três formas de escrita:

Hieróglifos egípcios.

Escrita demótica.

Grego antigo.

É importante compreender que não eram três línguas inteiramente distintas: hieróglifos e demótico registravam formas do egípcio, enquanto a terceira versão estava em grego.

Por que isso foi extraordinário?

Porque os estudiosos conheciam o grego antigo.

A comparação entre as versões forneceu pistas para compreender os sistemas egípcios.

Thomas Young contribuiu significativamente para o processo de decifração.

Jean-François Champollion realizou avanços decisivos, apresentados em 1822, demonstrando a importância dos valores fonéticos na leitura dos hieróglifos.

O processo não foi simplesmente traduzir um símbolo isolado.

Foi necessário reconhecer relações entre nomes, sinais e sistemas linguísticos.

A ligação com Thoth

Na mitologia egípcia, Thoth era associado à escrita, à sabedoria, aos registros e à contagem.

Ele funciona como nosso personagem simbólico para uma questão fundamental.

O que acontece quando uma mesma informação precisa atravessar sistemas de representação diferentes?

A Pedra de Roseta digital

No laboratório, imaginamos três representações:

Texto EBCDIC no COBOL.

Texto Unicode no Java.

Texto UTF-8 na mensagem JSON.

As representações podem ser diferentes.

O conteúdo desejado deve permanecer o mesmo.

Mas há uma diferença importante em relação à Pedra de Roseta histórica.

A conversão de caracteres em computadores envolve tabelas, codificações e algoritmos.

Ela não é automaticamente uma tradução linguística.

O sistema pode transformar corretamente os bytes de uma codificação em outra sem traduzir português para inglês, por exemplo.

Converter caracteres não é traduzir palavras. É preservar os caracteres através de representações diferentes.



🔤 Capítulo II — Caractere, código e byte: três conceitos que não podem ser confundidos

Antes de investigar os CCSIDs, precisamos compreender três conceitos.

O caractere

Um caractere é uma unidade abstrata de texto.

Por exemplo:

A

Ou:

Ç

Ou:

ã

O caractere é aquilo que desejamos representar.

O ponto de código

Unicode associa números a caracteres e a outros elementos do sistema de escrita.

Por exemplo:

A letra A corresponde a U+0041.

A letra Ç corresponde a U+00C7.

A letra ã corresponde a U+00E3.

Esses identificadores não significam que os caracteres sempre ocupem a mesma quantidade de bytes.

A codificação

Uma codificação determina como a informação é representada em unidades de armazenamento.

UTF-8 é uma codificação de Unicode.

UTF-16 também.

UTF-32 é outra.

EBCDIC pertence a uma família historicamente distinta de codificações de caracteres.

O erro fundamental

Imagine que uma aplicação receba os bytes que representam um texto em UTF-8.

Mas decida interpretá-los usando uma página de códigos EBCDIC.

O resultado poderá ser completamente diferente.

Os bytes não mudaram.

Mudou a regra usada para interpretá-los.

Isso é comparável a observar uma inscrição egípcia e tentar lê-la usando um alfabeto inadequado.

Uma observação para o programador iniciante

ASCII, EBCDIC, Unicode e UTF-8 não são quatro conceitos perfeitamente equivalentes.

ASCII é um conjunto de caracteres codificados historicamente importante.

EBCDIC designa uma família de codificações.

Unicode é um padrão amplo de representação de texto.

UTF-8 é uma forma de codificar caracteres Unicode em bytes.

Colocá-los todos numa mesma categoria sem distinções pode criar confusões técnicas.



🧱 Capítulo III — EBCDIC: o alfabeto digital que atravessou gerações de mainframes

EBCDIC significa Extended Binary Coded Decimal Interchange Code.

É uma família de codificações de caracteres associada historicamente aos sistemas IBM.

Não existe uma única versão universal de EBCDIC utilizada em todas as situações.

Há diferentes páginas de códigos.

Algumas atendem a necessidades linguísticas e regionais.

Outras possuem características associadas a determinados ambientes de software.

Por que a IBM utilizou EBCDIC?

A história do EBCDIC está relacionada à evolução de sistemas anteriores, equipamentos comerciais, tecnologias de cartões perfurados e arquiteturas de processamento de dados.

É parte importante da herança técnica do mainframe.

Isso não significa que sistemas IBM Z modernos estejam restritos ao EBCDIC.

O z/OS e seus subsistemas oferecem diferentes mecanismos de suporte e conversão de codificações, incluindo Unicode.

O problema do legado

Imagine um arquivo sequencial produzido há décadas.

O campo NOME contém caracteres codificados em determinada página EBCDIC.

O programa conhece implicitamente essa convenção.

Anos depois, uma API precisa enviar o nome a uma aplicação Java.

Se ninguém documentar a página de códigos real, a integração poderá assumir uma codificação incorreta.

E o arquivo original não precisa estar danificado para isso ocorrer.

O caso do Brasil

A página IBM-037 é uma das codificações EBCDIC relacionadas a ambientes que incluem Brasil e Portugal.

Isso não significa que todo mainframe brasileiro utilize CCSID 037.

Uma instalação pode utilizar outra página de códigos, dependendo de sua história e configuração.

O correto é verificar o ambiente real, não presumir o CCSID pelo país.


🔐 Capítulo IV — CCSID 037, 1047 e 1208: três portas para representar caracteres

CCSID significa Coded Character Set Identifier.

Um CCSID identifica uma codificação de caracteres reconhecida pelos componentes IBM.

Vamos conhecer os três identificadores centrais desta investigação.

CCSIDFamíliaCaracterística
037EBCDICPágina de códigos de byte único usada em vários contextos regionais
1047EBCDICPágina frequentemente encontrada em ambientes z/OS e ferramentas de desenvolvimento
1208Unicode UTF-8Codificação de comprimento variável, amplamente utilizada em integrações modernas

A documentação da IBM identifica explicitamente os três.

O que distingue 037 e 1047?

Ambos representam caracteres em uma codificação EBCDIC de byte único.

Mas existem diferenças em determinados pontos de mapeamento.

Isso importa, por exemplo, para símbolos usados em linguagens de programação e ferramentas.

Não devemos concluir que todos os caracteres acentuados serão necessariamente perdidos ao converter entre essas duas páginas.

Também não devemos afirmar que as páginas são intercambiáveis em todos os bytes.

Por que 1208 é diferente?

CCSID 1208 identifica UTF-8.

Em UTF-8, caracteres ASCII básicos utilizam um byte.

Outros caracteres podem utilizar dois, três ou quatro bytes.

Isso permite representar um repertório muito mais amplo de caracteres do que uma página EBCDIC tradicional de byte único.

A armadilha

O número 1208 não é uma espécie de versão superior do 037.

São identificadores de codificações diferentes.

O processo de conversão deve conhecer a origem e o destino.

Não existe uma conversão confiável quando a codificação original é apenas uma suposição.


<WritingBlock id="58322" variant="document">## 🧪 Capítulo V — O nome João Gonçalves: quando os bytes contam uma história diferente

Vamos reproduzir o incidente.

O nome original é:

JOÃO GONÇALVES

A aplicação Java espera receber uma sequência UTF-8 que represente exatamente esses caracteres.

Mas o texto atravessou diferentes componentes.

Primeiro foi armazenado em um campo COBOL.

Depois foi enviado através do CICS.

Em seguida passou pelo Java.

Finalmente foi serializado em JSON.

O nome em UTF-8

Considere somente a palavra:

JOÃO

Os caracteres são:

J, O, Ã, O.

Em Unicode:

CaracterePonto de códigoUTF-8 hexadecimal
JU+004A4A
OU+004F4F
ÃU+00C3C3 83
OU+004F4F

Portanto, a palavra possui quatro caracteres Unicode e cinco bytes UTF-8.

Uma diferença pequena, mas fundamental.

A armadilha de interpretar os bytes novamente

Agora imagine que os bytes UTF-8 de à sejam tratados como caracteres da codificação Windows-1252.

A sequência C3 83 passa a ser interpretada como dois caracteres.

O resultado textual pode se transformar em:

Ã

Esse texto, se for novamente codificado em UTF-8, produzirá uma sequência maior que a original.

Esse tipo de erro é conhecido popularmente como mojibake: caracteres exibidos incorretamente porque os bytes foram decodificados com a codificação errada.

Uma distinção fundamental

A transformação exemplificada acima é UTF-8 interpretado como Windows-1252.

Ela não é, por si só, uma demonstração de conversão EBCDIC incorreta.

Num ambiente IBM Z real, precisamos examinar os bytes e os CCSIDs efetivamente utilizados para descobrir em qual fronteira aconteceu o erro.

Não devemos olhar para qualquer caractere estranho e concluir automaticamente:

“Foi culpa do EBCDIC.”

O perigo de converter duas vezes

Imagine o fluxo:

Texto original em EBCDIC.

Conversão adequada para UTF-8.

Uma segunda rotina interpreta os bytes UTF-8 como se estivessem em outra codificação.

A aplicação grava o resultado incorreto.

A operação de transporte pode continuar funcionando.

O erro já não está nos bytes originais.

Está no texto transformado por uma interpretação equivocada.

O que o investigador deve procurar?

Os bytes antes da primeira conversão.

O CCSID real da origem.

O CCSID declarado ao componente de conversão.

Os bytes após a conversão.

O texto interpretado pelo Java.

O resultado serializado para JSON.

O conteúdo efetivamente recebido pelo consumidor da API.

A primeira etapa em que o texto muda é a principal pista.


🐍 Capítulo VI — Caracteres perdidos: quando uma conversão não consegue ser desfeita

O veterano apresenta outro problema.

Nem todas as conversões são reversíveis.

Imagine um nome contendo um caractere que não existe no repertório da página de códigos de destino.

Quando uma aplicação tenta representar esse nome em uma codificação limitada, pode ocorrer uma condição de erro ou substituição, dependendo dos serviços e das opções utilizadas.

O caractere de substituição

Em algumas conversões, um caractere não representável pode ser substituído por outro símbolo.

O valor exato e o comportamento dependem do mecanismo.

Isso é especialmente perigoso quando a aplicação aceita o resultado sem registrar que uma substituição ocorreu.

O caso do emoji

Imagine um nome de exibição que contenha:

ANA 😊

UTF-8 pode representar o emoji.

Uma página EBCDIC tradicional de byte único não possui necessariamente um caractere equivalente.

Se a aplicação converter o texto para uma página incapaz de representá-lo e substituir o emoji por um símbolo genérico, a informação original poderá ser perdida.

Converter o resultado novamente para UTF-8 não restaura automaticamente o emoji desaparecido.

Perda irreversível

Uma cadeia de conversão pode produzir:

Original → substituição → armazenamento → leitura.

A última leitura pode ser tecnicamente correta.

Mas ela reproduzirá o valor substituído, e não o original.

É por isso que a IBM documenta os riscos de substituições durante processos de conversão e migração para Unicode.

Nomes reais também oferecem desafios

Nomes podem conter:

Acentos.

Cedilhas.

Hífens.

Apóstrofos.

Caracteres de diferentes alfabetos.

Marcas diacríticas.

E combinações que não pertencem ao repertório de uma página de códigos antiga.

Em sistemas de identificação de pessoas, isso não é um detalhe estético.

Uma transformação incorreta pode prejudicar pesquisas, conciliações e correspondências entre cadastros.

Se uma informação foi substituída durante a conversão, o sistema não consegue garantir sua reconstrução apenas convertendo os bytes novamente.


🏛️ Capítulo VII — CICS CHAR e BIT: o escriba deve conhecer o conteúdo

No episódio anterior, utilizamos cinco containers CICS.

Agora vamos aprofundar o tratamento de caracteres.

Um container pode ser classificado como CHAR ou BIT.

CHAR

Representa dados de caracteres.

O CICS oferece serviços de conversão entre codificações suportadas.

Por exemplo, podemos colocar texto em um container utilizando a opção FROMCCSID.

Depois, o receptor pode solicitar o conteúdo em outra codificação usando INTOCCSID.

BIT

Representa dados binários.

Não está sujeito ao mesmo mecanismo de conversão de caracteres.

É apropriado quando precisamos preservar a representação binária de um conteúdo como COMP-3, conforme o contrato.

Exemplo didático de PUT CONTAINER

       EXEC CICS PUT CONTAINER('FIN-CLIENTE')
            CHANNEL('FINCHAN')
            FROM(WS-NOME)
            FLENGTH(LENGTH OF WS-NOME)
            FROMCCSID(WS-CCSID-ORIGEM)
            RESP(WS-RESP)
       END-EXEC

WS-CCSID-ORIGEM precisa conter o CCSID real dos bytes enviados.

Não basta inserir o número 037 porque o sistema está instalado no Brasil.

O CICS trata os dados como CHAR quando FROMCCSID é especificado.

Exemplo didático de GET CONTAINER

       EXEC CICS GET CONTAINER('FIN-CLIENTE')
            CHANNEL('FINCHAN')
            INTO(WS-NOME-UTF8)
            FLENGTH(WS-TAMANHO)
            INTOCCSID(WS-CCSID-DESTINO)
            RESP(WS-RESP)
       END-EXEC

O CCSID de destino poderia ser 1208 se o projeto exigir UTF-8 e a conversão for suportada no ambiente.

O programa precisa dimensionar adequadamente a área de destino e tratar as condições de retorno.

A armadilha de FLENGTH

O comprimento do texto pode mudar após a conversão.

Um campo EBCDIC de dez caracteres pode ocupar dez bytes.

Sua representação UTF-8 poderá ocupar mais bytes se contiver determinados caracteres.

Portanto, não devemos confundir quantidade de caracteres com comprimento em bytes.

O cuidado com estruturas mistas

Um copybook que contém texto EBCDIC e números COMP-3 não deve ser enviado inteiro como CHAR na expectativa de que o CICS identifique automaticamente quais campos devem ser traduzidos.

O mecanismo não interpreta arbitrariamente o layout COBOL.

Ele segue as regras do container e do serviço de conversão.

Converter corretamente exige conhecer a origem, o destino e a natureza real dos dados.


☕ Capítulo VIII — Java: quando uma String não é um arquivo de bytes

O desenvolvedor Java apresenta sua implementação.

O programa recebe dados do CICS.

Depois cria um objeto de negócio.

Finalmente produz JSON.

O veterano pergunta:

— Você está tratando esses dados como String ou como byte[]?

O desenvolvedor responde:

— String.

— E em qual etapa os bytes foram decodificados?

Essa pergunta muda toda a investigação.

String Java

Uma String Java representa uma sequência de unidades de código UTF-16 e oferece métodos para trabalhar com texto Unicode.

Ela não é simplesmente um array UTF-8.

Quando uma aplicação Java lê dados externos, a decodificação dos bytes precisa ser compatível com a origem.

byte[]

Um byte[] contém bytes.

Sem conhecer a codificação, não podemos concluir qual texto esses bytes representam.

O mesmo array pode produzir textos distintos se for decodificado usando codificações diferentes.

O erro clássico

String nome = new String(bytes);

Esse construtor utiliza a codificação padrão do ambiente Java.

Em ambientes modernos, essa codificação frequentemente será UTF-8, mas depender implicitamente dela não é adequado quando os dados possuem um contrato explícito.

Se os bytes forem EBCDIC, interpretá-los como UTF-8 poderá produzir resultados errados.

A abordagem conceitualmente correta

String nome = new String(
    bytes,
    java.nio.charset.Charset.forName("IBM037")
);

Esse exemplo pressupõe que os bytes realmente utilizem IBM037 e que a implementação Java disponha desse charset.

Se forem IBM1047, a escolha precisará corresponder à codificação verdadeira.

Se já forem UTF-8, não devemos decodificá-los como EBCDIC.

O risco do conserto duplo

Imagine que a API JCICS já tenha retornado uma String corretamente convertida.

O desenvolvedor transforma essa String em bytes usando uma codificação e tenta reinterpretá-los por outra.

A nova etapa poderá introduzir o erro que não existia.

Por isso, o investigador precisa saber o que cada método já realizou.

Não se deve converter novamente um texto apenas porque ele veio de um mainframe.


📜 Capítulo IX — JSON: o documento moderno que também precisa respeitar a codificação

Agora chegamos à fronteira externa do banco.

Uma API envia uma resposta JSON.

Exemplo:

{
  "transferencia": "FIN-990217",
  "beneficiario": "João Gonçalves",
  "valor": "1250000000.00",
  "moeda": "BRL",
  "status": "APPROVED"
}

O campo valor foi representado como string decimal por escolha didática do contrato.

Outras arquiteturas podem utilizar números JSON, respeitando os limites de precisão dos consumidores.

JSON e Unicode

JSON representa dados textuais e sua interoperabilidade depende de regras padronizadas de codificação.

Na comunicação aberta entre sistemas, JSON deve utilizar UTF-8 segundo as regras atuais de interoperabilidade.

Mas um programa COBOL pode trabalhar internamente com uma representação diferente antes da serialização.

JSON GENERATE no Enterprise COBOL

O Enterprise COBOL oferece a instrução JSON GENERATE.

A documentação IBM descreve regras específicas de codificação para os documentos gerados, incluindo UTF-8 em determinados formatos de receptor.

Isso significa que o desenvolvedor precisa compreender o tipo do receptor e as opções utilizadas.

Não deve pressupor que o JSON terá sempre exatamente a mesma representação dos campos COBOL de origem.

O problema da dupla serialização

Imagine que o Java receba corretamente:

João Gonçalves

Depois gere uma resposta JSON por uma biblioteca apropriada.

Até aqui, a informação pode estar correta.

Mas uma camada posterior altera o cabeçalho de codificação ou interpreta incorretamente a sequência UTF-8.

O navegador recebe caracteres estranhos.

O problema pode estar na resposta HTTP ou em uma conversão intermediária, não necessariamente no Db2 ou no COBOL.

O que inspecionar?

A String antes da serialização.

Os bytes reais enviados pela API.

O cabeçalho Content-Type.

A codificação efetiva da resposta.

O comportamento do cliente consumidor.

E os logs de integração.

Um JSON sintaticamente válido não garante que os dados textuais tenham sido preservados desde a origem.


🔬 Laboratório — A Pedra de Roseta Digital

Experimente como a mesma palavra muda de representação sem necessariamente mudar de significado.

{@body const [palavra,setPalavra] = DIL.useState("JOÃO")}
{@body const exemplos = ["JOÃO","GONÇALVES","MAAT","AÇÃO","€","😊"]}
{@body const u8 = s => Array.from(s).flatMap(c=>{const x=c.codePointAt(0);if(x<128)return [x];if(x<2048)return [192|(x>>6),128|(x&63)];if(x<65536)return [224|(x>>12),128|((x>>6)&63),128|(x&63)];return [240|(x>>18),128|((x>>12)&63),128|((x>>6)&63),128|(x&63)]})}
{@body const hex = n=>n.toString(16).toUpperCase().padStart(2,"0")}
<box border radius="xl" padding={3} gap={3}>
<text weight="medium">Escolha um texto Unicode</text>
<radio-group direction="row" value={palavra} onChange={setPalavra}>
{#each exemplos as e}
<radio key={e} value={e}>{e}</radio>
{/each}
</radio-group>
<grid columns={2} gap={2}>
<grid-item>
<box background="surface-secondary" radius="lg" padding={3} gap={1}>
<caption>Caracteres Unicode</caption>
<title size="2xl" tabularNums>{Array.from(palavra).length}</title>
</box>
</grid-item>
<grid-item>
<box background="surface-secondary" radius="lg" padding={3} gap={1}>
<caption>Bytes UTF-8 • CCSID 1208</caption>
<title size="2xl" tabularNums>{u8(palavra).length}</title>
</box>
</grid-item>
</grid>
<box gap={2}>
<text weight="medium">Bytes UTF-8 em hexadecimal</text>
<row wrap="wrap" gap={1}>
{#each u8(palavra) as b,i}
<box key={i} background="surface-tertiary" border radius="sm" padding={2}>
<text weight="medium" tabularNums>{hex(b)}</text>
</box>
{/each}
</row>
<text size="sm" color="secondary">Pontos de código: {Array.from(palavra).map(c=>"U+"+c.codePointAt(0).toString(16).toUpperCase().padStart(4,"0")).join(" · ")}</text>
</box>
<divider color="subtle"/>
<text size="sm">UTF-8 representa todos esses exemplos Unicode. Já uma codificação EBCDIC tradicional de byte único possui repertório limitado, e a conversão precisa ser testada com a página de códigos concreta.</text>

<caption>Esta demonstração calcula UTF-8, não simula a codificação IBM037 ou IBM1047. Caracteres combinantes podem fazer a quantidade de caracteres percebidos visualmente diferir da contagem de pontos de código.</caption> </box>

<WritingBlock id="58323" variant="document">## 🔍 Capítulo X — A investigação forense: como descobrir onde o nome foi transformado

O veterano reúne os especialistas.

— Precisamos parar de procurar o culpado pela aparência do texto. Vamos identificar a primeira fronteira onde a informação mudou.

Primeira etapa — Preservar a origem

A equipe identifica o valor autorizado do nome.

Não basta copiar aquilo que aparece incorretamente no relatório.

É necessário encontrar uma fonte confiável: cadastro original, mensagem recebida, registro de origem ou outra evidência independente.

Segunda etapa — Examinar os bytes no COBOL

O campo alfanumérico é analisado segundo seu layout e sua codificação real.

É preciso verificar se o texto está correto antes de entrar no CICS.

Um dump hexadecimal controlado pode ajudar.

Mas esse tipo de coleta exige cuidados para não expor dados pessoais ou financeiros em logs de diagnóstico.

Terceira etapa — Examinar o container CICS

Verifique o nome do container.

Seu DATATYPE.

O CCSID de origem.

O comprimento.

E os resultados das operações PUT e GET.

Se houver conversão, determine quais codificações foram solicitadas.

Quarta etapa — Examinar o Java

A equipe verifica se os dados chegaram como String ou byte[].

Se houve uma decodificação explícita, qual charset foi utilizado?

Se a API JCICS já realizou a conversão, existe outra transformação posterior?

Quinta etapa — Examinar a serialização JSON

Antes de gerar os bytes da resposta, a aplicação ainda possui o nome correto?

O serializador produz UTF-8?

O contrato da API especifica a representação apropriada?

Sexta etapa — Examinar o consumidor externo

A resposta chega com os bytes esperados?

O cliente interpreta a codificação correta?

Existe uma aplicação intermediária executando outra conversão?

Sétima etapa — Identificar a primeira divergência

O objetivo é localizar o primeiro ponto em que:

JOÃO

deixa de representar os caracteres originais.

Se a informação já aparece errada no COBOL, investigar exclusivamente o Java não resolverá a causa.

Se permanece correta até a serialização JSON, o Db2 pode não ter qualquer relação com a transformação.

O papel dos hashes

Comparar hashes de bytes pode ajudar quando precisamos detectar alterações exatas na representação binária.

Mas uma conversão legítima de EBCDIC para UTF-8 altera os bytes, mesmo preservando os caracteres.

Portanto, o hash bruto não deve ser utilizado como único critério de equivalência textual entre codificações diferentes.

Podemos comparar o texto após decodificação controlada e, quando exigido pelo contrato, após uma normalização Unicode definida.

A investigação precisa distinguir igualdade de bytes, igualdade de caracteres e equivalência de identidade empresarial.


🧩 Capítulo XI — Unicode NFC e NFD: quando dois nomes iguais possuem bytes diferentes

O programador encontra outra surpresa.

Dois textos aparecem visualmente iguais.

Mas a comparação byte a byte produz resultados diferentes.

Como isso é possível?

Unicode permite representar determinadas sequências textuais de maneiras diferentes.

Considere a letra é.

Ela pode ser representada como um único ponto de código:

U+00E9

Ou como uma sequência contendo:

U+0065 — letra e.

U+0301 — acento agudo combinante.

Essas sequências podem parecer idênticas ao leitor.

Mas possuem pontos de código e sequências UTF-8 diferentes.

Normalização Unicode

Unicode define formas de normalização, como NFC e NFD.

NFC utiliza uma forma de composição canônica.

NFD utiliza uma forma de decomposição canônica.

Elas permitem tratar determinadas equivalências de representação de maneira consistente.

O perigo para o cadastro

Imagine duas aplicações.

Uma grava um nome em NFC.

Outra grava uma sequência canonicamente equivalente em NFD.

Se o sistema comparar somente os bytes, poderá considerar os registros diferentes.

A solução é remover os acentos?

Não necessariamente.

Remover acentos pode alterar nomes legítimos e produzir colisões entre pessoas diferentes.

A normalização Unicode é diferente da remoção indiscriminada de diacríticos.

E quanto a maiúsculas?

Converter nomes para maiúsculas também exige atenção às regras linguísticas.

Nem todas as transformações de caixa são triviais para todos os idiomas.

A identidade precisa de um identificador confiável

Em nosso banco fictício, a transferência deve utilizar identificadores de cliente definidos pelo negócio.

O nome pode servir como atributo de identificação e conferência.

Mas não deveria ser a única chave técnica para determinar a conta financeira de destino.

A grafia pode mudar.

A pessoa pode alterar legalmente seu nome.

Diferentes pessoas podem possuir nomes iguais.

Por isso, o tratamento de Unicode precisa estar associado a uma arquitetura de identidade adequada.


🛡️ Capítulo XII — Quando um nome errado vira um incidente de segurança

O gerente pergunta:

— Se o dinheiro foi enviado à conta correta, por que precisamos investigar tanto o nome?

O veterano responde:

— Porque sistemas financeiros dependem de identidade, rastreabilidade e reconciliação.

Imagine uma operação com nome corrompido.

O identificador bancário pode continuar correto.

Mas o sistema de auditoria não consegue correlacionar adequadamente o nome apresentado com o cadastro autorizado.

Uma ferramenta antifraude pode receber um valor diferente daquele esperado.

Uma equipe operacional pode abrir uma investigação desnecessária.

Ou uma busca nominal pode deixar de localizar um registro.

Cuidado com conclusões precipitadas

Não devemos afirmar que qualquer alteração de acento provocará automaticamente fraude, rejeição de transferência ou falha de compliance.

O impacto depende das regras dos sistemas envolvidos.

Mas divergências de texto podem comprometer controles de identificação quando esses controles utilizam os campos afetados.

Três medidas importantes

A primeira é preservar os identificadores técnicos e empresariais autorizados.

A segunda é manter contratos claros de representação textual.

A terceira é registrar evidências suficientes para detectar alterações inesperadas sem expor desnecessariamente informações pessoais.

A lição de RACF

RACF pode controlar acessos e fornecer informações de auditoria conforme a configuração.

Mas não verifica automaticamente se uma aplicação transformou um nome Unicode de maneira semanticamente correta.

Segurança de acesso e integridade de conteúdo são dimensões diferentes.


🥚 Capítulo XIII — Dez segredos da Pedra de Roseta digital

1 — Unicode não é sinônimo de UTF-8. UTF-8 é uma forma de codificar Unicode.

2 — EBCDIC não possui uma única página universal. CCSIDs diferentes podem possuir mapeamentos distintos.

3 — CCSID 037 e 1047 não são nomes intercambiáveis. É necessário utilizar o identificador correspondente à origem real.

4 — CCSID 1208 representa UTF-8. Seu comprimento em bytes varia conforme os caracteres.

5 — Um acento pode aumentar o comprimento UTF-8. O número de bytes não corresponde sempre ao número de caracteres.

6 — CHAR e BIT não representam a mesma responsabilidade. A conversão de caracteres não deve transformar indiscriminadamente dados binários.

7 — Java String não é um arquivo EBCDIC nem um array UTF-8. Ela representa texto, e a transformação em bytes exige uma codificação.

8 — JSON válido pode conter um nome errado. Sintaxe correta não garante que a informação original foi preservada.

9 — Converter novamente não recupera necessariamente caracteres substituídos. Se houve perda irreversível, precisamos de uma fonte original confiável.

10 — Dois nomes visualmente idênticos podem possuir sequências Unicode diferentes. A normalização e as regras de comparação precisam ser definidas.


⚖️ Capítulo XIV — O julgamento de Thoth: quem mudou a identidade do cliente?

O tribunal está aberto.

O COBOL apresenta o cadastro original.

O CICS apresenta os dados do channel.

O Java apresenta a String recebida.

A API apresenta a resposta JSON.

O Db2 apresenta os registros de negócio.

Thoth, nosso escriba simbólico, examina a sequência de transformações.

O resultado da investigação

No cenário fictício, o nome estava correto na origem.

A primeira conversão para UTF-8 havia preservado a informação.

O erro aconteceu depois, quando uma rotina intermediária interpretou novamente os bytes UTF-8 utilizando uma codificação incompatível.

O texto resultante foi armazenado e transmitido como se fosse a informação correta.

Não houve evidência de que a transação financeira tivesse sido alterada.

Mas o nome exibido deixou de corresponder ao cadastro.

A correção

A equipe eliminou a interpretação redundante.

Documentou os CCSIDs utilizados em cada fronteira.

Introduziu testes com nomes acentuados.

Separou conteúdo textual e binário.

Validou o JSON produzido.

Criou testes de ida e volta entre os formatos suportados.

E estabeleceu uma política explícita de normalização Unicode para os campos em que ela era apropriada.

O veredito

O gerente pergunta:

— Então foi o EBCDIC que mudou o nome?

— Não. O problema demonstrado foi a interpretação inadequada de bytes já codificados em UTF-8.

— Mas o mainframe continuou funcionando!

— Sim. O funcionamento da infraestrutura não garante que todas as transformações de dados de uma aplicação estejam corretas.

— E como impedimos isso de acontecer novamente?

— Tratando a codificação como parte do contrato, não como uma escolha implícita de cada programa.


☕ Epílogo — 03h17: Thoth finalmente reconheceu o verdadeiro nome

O Banco de Mênfis conclui os testes.

O cadastro original continua preservado.

O COBOL produz os dados conforme seu contrato.

O CICS aplica os mecanismos de conversão apropriados.

O Java recebe os caracteres corretos.

O JSON transporta o nome em UTF-8.

O consumidor exibe:

JOÃO GONÇALVES

O gerente sorri.

— Finalmente encontramos o cliente!

O veterano responde:

— Encontramos a etapa que alterava a representação do nome.

— Então a Pedra de Roseta resolveu o problema?

— A metáfora nos ensinou a procurar o sistema de escrita correto para cada inscrição.

— E o segredo de Thoth?

— Não basta preservar uma sequência de símbolos. É necessário conhecer as regras que permitem interpretá-los.

O programador fecha o livro de arqueologia.

Na imagem, três inscrições aparecem sobre a mesma pedra.

Hieróglifos.

Demótico.

Grego.

Diferentes sistemas de escrita permitiram que estudiosos recuperassem conhecimentos perdidos havia séculos.

No laboratório, diferentes codificações foram reconciliadas para preservar os caracteres originais de um nome.

O relógio marca 03h17.

O veterano termina seu café.

E registra:

O pior erro de codificação nem sempre é aquele que impede um sistema de funcionar. Às vezes é aquele que permite a operação continuar enquanto o significado dos dados se perde pelo caminho.


🏺 A última lição do Mestre Jedi do Mainframe

EBCDIC representa uma família histórica de codificações utilizada em sistemas IBM.

CCSID 037 e 1047 identificam páginas EBCDIC distintas.

CCSID 1208 identifica UTF-8.

Unicode permite representar caracteres de diferentes sistemas de escrita.

CICS fornece conversão apropriada para containers de caracteres.

Java exige uma interpretação coerente entre bytes e strings.

Db2 possui mecanismos de codificação e conversão que precisam ser configurados e compreendidos.

JSON permite transmitir informações textuais modernas, mas não repara automaticamente caracteres corrompidos antes da serialização.

E os sistemas financeiros precisam preservar tanto a representação quanto a identidade empresarial.

Porque a verdadeira Pedra de Roseta do IBM Z não é um conversor milagroso de bytes. É um contrato explícito que permite a cada sistema interpretar os caracteres como foram originalmente concebidos.

☕ Bellacosa Mainframe — Onde Thoth traduz os papiros, Tutancâmon protege os registros, Anúbis vigia as fronteiras entre sistemas e o COBOL aprende que uma letra pode sobreviver a milhares de anos, mas também pode se perder numa única conversão mal configurada.

terça-feira, 3 de novembro de 2026

📜 O Papiro das Mil Faces no CICS: Channels, Containers, CCSID e Conversão COBOL/Java no IBM Z

 

Bellacosa Mainframe e os detalhes do cics

☕ UM CAFÉ NO BELLACOSA MAINFRAME

📜 O PAPIRO DAS MIL FACES NO CICS: CINCO CONTAINERS, DOIS PROGRAMAS E UM TESOURO QUE MUDOU DE IDENTIDADE — PUT CONTAINER, GET CONTAINER, FLENGTH, CCSID, BIT, CHAR E A CONVERSÃO SILENCIOSA NO IBM Z!

São 03h17. Um programa COBOL organiza uma transferência de R$ 1,25 bilhão em cinco containers de um mesmo channel. O CICS executa o LINK, o programa Java recebe os dados e nenhuma falha de comunicação é registrada. Entretanto, o nome do beneficiário chega com caracteres estranhos, o comprovante binário está sendo tratado como texto e um valor COMP-3 corre o risco de ser interpretado como caracteres. Uma investigação sobre o transporte de informações, a diferença entre bytes e significado, a conversão EBCDIC/UTF-8 e os perigos de um papiro que assume mil faces dependendo de quem o lê.



🎬 Prólogo — 03h17: cinco papiros atravessaram o templo, mas um deles mudou de rosto

São Paulo, 19 de novembro de 2026.

03h17.

O Banco de Mênfis acabara de modernizar a passagem de dados entre programas COBOL e Java.

No episódio anterior, duas aplicações haviam interpretado incorretamente uma COMMAREA.

O problema fora provocado por layouts incompatíveis.

Um programa esperava dezessete bytes.

Outro enviava dezenove.

A equipe decidiu avançar com uma arquitetura baseada em channels e containers.

Agora, em vez de transportar uma única estrutura monolítica, o programa emissor organizava os dados em cinco containers.

O canal recebeu o nome:

FINCHAN

Os containers foram definidos como:

FIN-HEADER

FIN-VALOR

FIN-CLIENTE

FIN-DOC

FIN-STATUS

A equipe comemorou.

— Finalmente não precisamos mais colocar tudo em uma COMMAREA!

O novo programa COBOL executou sua primeira operação importante.

R$ 1.250.000.000,00.

O CICS recebeu os containers.

O programa Java foi chamado.

O processamento terminou.

Mas o relatório de homologação apresentou uma surpresa.

O nome do beneficiário, que deveria ser:

João Gonçalves

Apareceu com caracteres incorretos.

O comprovante financeiro não podia ser interpretado corretamente.

E um diagnóstico revelou que a equipe estava considerando transportar um campo COMP-3 pelo mesmo caminho de conversão usado para textos.

O gerente perguntou:

— O tesouro foi roubado?

— Não encontramos evidência de alteração financeira.

— Então os dados se perderam?

— Ainda precisamos examinar a codificação e a representação de cada container.

— Mas o CICS não converte os dados automaticamente?

O veterano aproximou-se.

— Converte determinados dados de caracteres, quando o protocolo e as opções exigem. Não significa que qualquer sequência de bytes possa ser convertida como texto.

O gerente franziu a testa.

— O que há de errado em tratar os cinco containers da mesma forma?

O veterano retirou um papiro ilustrado.

Thoth, o deus escriba, aparecia registrando símbolos.

— Porque um papiro pode conter nomes, números, desenhos e registros. Nem todos possuem a mesma representação. O erro começa quando alguém tenta interpretar tudo como se fosse uma única inscrição.

Ele escreveu no quadro:

UM CHANNEL ORGANIZA CONTAINERS. CADA CONTAINER PRECISA DE UM CONTRATO DE DADOS.

A investigação começa.



🏺 Capítulo I — Thoth e o papiro das mil faces: quando o significado dependia de quem sabia ler

Na religião egípcia, Thoth era uma divindade associada à escrita, ao conhecimento, à contagem, à sabedoria e aos registros.

Frequentemente representado com cabeça de íbis, também podia aparecer associado ao babuíno.

Seu papel como escriba dos deuses aparece em diferentes tradições religiosas.

Na conhecida cena da pesagem do coração, Thoth registra o resultado do julgamento.

Isso combina perfeitamente com a proposta da nossa série.

A escrita preserva informações.

Mas preservar símbolos não garante que todos consigam interpretá-los corretamente.

O valor de uma inscrição

Um papiro antigo pode conter escrita hieroglífica, hierática ou demótica, dependendo do período e do contexto.

Um leitor moderno que desconheça essas convenções poderá observar apenas desenhos e marcas.

O documento permanece fisicamente presente.

O significado, entretanto, exige conhecimento do sistema de escrita.

O mesmo acontece em computadores.

Um conjunto de bytes pode representar:

Um texto codificado em EBCDIC.

Um texto codificado em UTF-8.

Um número COMP-3.

Um inteiro binário.

Um documento PDF.

Uma imagem.

Uma sequência de controle.

Os bytes não anunciam universalmente seu significado.

É o contrato de dados que determina como interpretá-los.

A metáfora do papiro

Imagine cinco papiros.

O primeiro contém o nome do faraó.

O segundo contém seu tesouro expresso numericamente.

O terceiro contém uma lista de pessoas.

O quarto apresenta uma imagem.

O quinto registra uma decisão administrativa.

Seria inadequado interpretar uma imagem como uma lista de números.

Também seria inadequado tratar um número binário como uma frase.

No CICS, temos exatamente o mesmo problema.

A integridade de uma informação depende não apenas de sua transmissão, mas também da interpretação correta de sua representação.



🏛️ Capítulo II — Channel: o corredor que reúne cinco câmaras

No CICS Transaction Server, um channel reúne containers nomeados.

Um container é uma unidade de dados.

O channel oferece uma maneira de transportar essas unidades entre programas e determinados fluxos de execução.

A IBM descreve o channel como um conjunto de containers, com função semelhante à de uma lista de parâmetros.

Nosso canal financeiro

Criamos:

FINCHAN

Dentro dele colocamos cinco containers.

ContainerConteúdoRepresentação planejada
FIN-HEADERVersão e identificadorCHAR
FIN-VALORValor COMP-3 versionadoBIT
FIN-CLIENTENome do beneficiárioCHAR
FIN-DOCDocumento binárioBIT
FIN-STATUSSituação da operaçãoCHAR

Essa divisão é um projeto didático.

Não existe uma regra universal segundo a qual todo programa financeiro deva usar exatamente esses cinco containers.

O que muda em relação à COMMAREA?

Na COMMAREA tradicional, uma única estrutura poderia reunir todos os campos em posições físicas conhecidas.

Uma mudança no tamanho de um campo poderia deslocar os seguintes.

Com containers, é possível separar unidades independentes de informação.

Isso oferece maior flexibilidade para evoluir determinados contratos.

Mas atenção!

Se FIN-VALOR contém uma estrutura COMP-3, o consumidor precisa conhecer a definição desse container.

O problema de layout não desaparece.

Ele fica localizado dentro de uma unidade menor.

Os nomes importam

Um programa pode procurar:

FIN-CLIENTE

Enquanto outro escreveu:

FIN-CLIENTES

São identificadores diferentes.

O CICS não precisa presumir que ambos representam a mesma unidade.

Portanto, é necessário definir nomes estáveis e tratar explicitamente a ausência de containers esperados.

O mesmo cuidado vale para versões.

Uma interface pode utilizar FIN-VALOR-V2, por exemplo, desde que isso faça parte de uma política de compatibilidade definida.

Channel organiza. Container transporta. Contrato interpreta.



📦 Capítulo III — PUT CONTAINER: quando o escriba deposita um papiro no cofre

O primeiro comando fundamental é:

EXEC CICS PUT CONTAINER

Ele permite colocar dados em um container pertencente a um channel.

Um exemplo didático:

       EXEC CICS PUT CONTAINER('FIN-HEADER')
            CHANNEL('FINCHAN')
            FROM(WS-FIN-HEADER)
            FLENGTH(LENGTH OF WS-FIN-HEADER)
            DATATYPE(DFHVALUE(CHAR))
            RESP(WS-RESP)
       END-EXEC

Aqui declaramos que o conteúdo é texto.

O comando pode criar um container ou atualizar o conteúdo de um container existente, segundo as opções e a versão do CICS.

Uma curiosidade perigosa

O DATATYPE do container é estabelecido quando ele é criado.

Não devemos imaginar que escrever novamente em um container existente, desta vez especificando BIT ou CHAR, sempre transformará sua natureza.

A IBM esclarece que o tipo do container existente não é redefinido por uma nova operação PUT.

Isso cria uma armadilha.

Se um programa criou FIN-VALOR como CHAR, outro não deveria presumir que poderá simplesmente convertê-lo em BIT ao reescrever os dados com uma opção diferente.

A estratégia correta precisa respeitar o ciclo de vida do container e seu contrato.

Outra armadilha: sobrescrever dados

Em geral, escrever novamente no mesmo container substitui o conteúdo anterior, salvo opções específicas suportadas para outros comportamentos.

Portanto, repetir um PUT não deve ser confundido com acrescentar automaticamente uma nova transação a uma fila.

Channels não são, por si só, filas de mensageria persistente.

E containers comuns de channel não oferecem automaticamente as mesmas garantias transacionais de IBM MQ ou do banco de dados.

O que devemos validar?

Se o channel é o correto.

Se o nome do container corresponde ao contrato.

Se o DATATYPE está correto.

Se a área FROM contém dados válidos.

Se FLENGTH corresponde ao comprimento real.

E se a operação terminou com uma condição de retorno apropriada.


📥 Capítulo IV — GET CONTAINER: quando o receptor precisa saber qual papiro está abrindo

O segundo comando é:

EXEC CICS GET CONTAINER

Ele permite recuperar o conteúdo de determinado container.

Exemplo conceitual:

       EXEC CICS GET CONTAINER('FIN-HEADER')
            CHANNEL('FINCHAN')
            INTO(WS-FIN-HEADER)
            FLENGTH(WS-TAMANHO)
            RESP(WS-RESP)
       END-EXEC

A variável WS-TAMANHO deve possuir definição compatível com o formato esperado pelo comando.

No caso de GET com INTO, FLENGTH participa da informação sobre a capacidade de recebimento e retorna o comprimento efetivo do conteúdo recuperado.

Se houver conversão de caracteres, o comprimento retornado pode refletir o tamanho depois da conversão.

O risco de receber dados grandes demais

Imagine que o container FIN-CLIENTE contenha uma descrição de 300 bytes.

O programa receptor oferece uma área de somente 80 bytes.

É necessário tratar a condição de comprimento.

Não se deve presumir que todo GET colocará qualquer conteúdo em uma área insuficiente de maneira segura e adequada à aplicação.

A alternativa NODATA

O CICS fornece uma opção especialmente útil:

NODATA

Ela permite descobrir o comprimento de um container sem recuperar seu conteúdo naquele momento.

O receptor pode utilizar essa informação para planejar a leitura.

Entretanto, se houver conversão de caracteres, o tamanho na codificação de destino pode ser diferente.

Por isso, a consulta precisa considerar o CCSID pretendido.

O perigo do comprimento correto

Mesmo que o container possua exatamente oito bytes, isso não prova que ele contenha um valor COMP-3 válido.

Poderá conter oito bytes de outro formato.

O programa deve interpretar a representação conforme o contrato e validar o valor.

É a mesma lição da COMMAREA, agora aplicada a containers independentes.


🧭 O mapa do tesouro — um Channel, cinco Containers

<box border radius="xl" padding={3} gap={3}> <text color="secondary" weight="medium" size="xs">ARQUITETURA DIDÁTICA • FINCHAN</text> <box background="surface-secondary" radius="lg" padding={3} align="center" gap={1}> <icon name="server" size="lg"/> **COBOL — Programa emissor** <text size="xs" color="secondary">PUT CONTAINER</text> </box> <row justify="center"><icon name="arrow-down" color="secondary"/></row> <box border={{size:2,color:"strong"}} radius="lg" padding={3} gap={3}> <row align="center" justify="center" gap={2}> <icon name="boxes" size="lg"/> **CHANNEL FINCHAN** </row> <grid columns={2} gap={2}> {#each [{n:"FIN-HEADER",t:"CHAR",d:"Versão e identificação"},{n:"FIN-VALOR",t:"BIT",d:"Packed decimal COMP-3"},{n:"FIN-CLIENTE",t:"CHAR",d:"Nome em caracteres"},{n:"FIN-DOC",t:"BIT",d:"Documento binário"},{n:"FIN-STATUS",t:"CHAR",d:"Situação da transação"}] as c} <grid-item> <box background="surface-secondary" radius="md" padding={2} gap={1}> <row align="center" justify="between" wrap="wrap"> <text size="xs" weight="medium">{c.n}</text> <text size="3xs" color="secondary">{c.t}</text> </row> <text size="xs" color="secondary">{c.d}</text> </box> </grid-item> {/each} </grid> </box> <row justify="center"><icon name="arrow-down" color="secondary"/></row> <box background="surface-secondary" radius="lg" padding={3} align="center" gap={1}> <icon name="coffee" size="lg"/> **Java — Programa receptor** <text color="secondary" size="xs">GET CONTAINER / API JCICS</text> </box> <caption>O fluxo apenas transporta dados. Cada container precisa ser identificado, validado e interpretado conforme a sua representação.</caption> </box>

<WritingBlock id="76432" variant="document">## 🔤 Capítulo V — CCSID: a pedra de Roseta dos caracteres

Agora chegamos ao verdadeiro coração do incidente.

CCSID significa Coded Character Set Identifier.

Esse identificador informa uma codificação de caracteres reconhecida pelo ambiente.

Em sistemas IBM Z, é comum encontrar dados textuais em codificações EBCDIC.

Em sistemas Java e interfaces modernas, UTF-8 é frequentemente utilizado para representar texto em arquivos e protocolos, embora as strings Java sejam uma abstração de caracteres e não simplesmente um conjunto de bytes UTF-8.

Por que isso importa?

Imagine a palavra:

JOÃO

Em uma determinada codificação EBCDIC, ela possui uma representação em bytes.

Em UTF-8, possui outra.

Um consumidor que interprete bytes EBCDIC diretamente como UTF-8 poderá produzir caracteres incorretos ou falhas de decodificação.

O dado foi transportado.

Mas sua interpretação foi inadequada.

O papel de FROMCCSID

No PUT CONTAINER, FROMCCSID permite indicar o CCSID dos dados de caracteres enviados.

A documentação IBM também oferece FROMCODEPAGE para determinadas formas de identificação de página de códigos.

Quando FROMCCSID ou FROMCODEPAGE é especificado, o container é tratado como CHAR.

O papel de INTOCCSID

No GET CONTAINER, INTOCCSID permite solicitar a recuperação dos dados de caracteres em determinada codificação.

O CICS poderá executar a conversão apropriada, se ela for suportada e necessária.

Quando a opção não é especificada, o CCSID local da região participa do comportamento padrão.

Um exemplo

O container FIN-CLIENTE guarda o nome de um beneficiário.

O programa COBOL produz texto em uma codificação EBCDIC suportada.

O programa Java precisa receber uma string correspondente aos caracteres originais.

Se a interface usar corretamente o DATATYPE CHAR e a conversão aplicável, o processo poderá preservar o texto.

O problema do CCSID incorreto

Imagine declarar que os bytes já estão em UTF-8 quando, na realidade, foram produzidos em EBCDIC.

Nesse caso, o sistema recebe uma indicação falsa sobre a origem dos dados.

Mesmo que exista um mecanismo automático de conversão, ele não consegue adivinhar com segurança a codificação correta quando a informação fornecida está errada.

O que precisamos documentar?

A codificação de origem.

A codificação de destino.

Os caracteres permitidos.

O comportamento esperado para caracteres não representáveis.

O tratamento de erros de conversão.

E os testes com acentos, pontuação e caracteres não ASCII.

A pedra de Roseta não era mágica.

Ela fornecia informações que permitiam relacionar sistemas de escrita.

No CICS, o CCSID desempenha uma função técnica semelhante dentro da nossa metáfora.

Para converter corretamente um texto, precisamos saber como seus caracteres foram codificados.


🐍 Capítulo VI — CHAR versus BIT: a maldição que pode destruir o tesouro

O DBA apresenta duas palavras.

CHAR

BIT

Elas parecem simples.

Mas representam uma decisão fundamental.

CHAR: dados de caracteres

Quando um container possui DATATYPE CHAR, seus dados estão sujeitos aos mecanismos de conversão de caracteres aplicáveis.

Isso é apropriado para conteúdo genuinamente textual.

Exemplos:

Nome do cliente.

Descrição de uma operação.

Mensagem textual.

Código alfanumérico definido por um contrato de caracteres.

BIT: dados binários

Quando um container possui DATATYPE BIT, seus bytes não são convertidos pelo mecanismo de conversão de caracteres do CICS.

Isso é adequado para dados que devem preservar exatamente sua representação binária.

Exemplos:

Campos COMP-3.

Inteiros binários armazenados em formato específico.

Documentos PDF.

Imagens.

Blocos binários definidos por contrato.

A maldição do COMP-3

Imagine um campo COBOL:

       05 FIN-VALOR
          PIC S9(12)V99 COMP-3.

Esse campo possui oito bytes em packed decimal.

Não é uma string de oito caracteres.

Contém nibbles que representam dígitos decimais e sinal.

Se ele for colocado em um container CHAR e submetido a uma conversão de caracteres incompatível, os bytes podem ser transformados como se representassem texto.

O resultado não terá necessariamente o mesmo significado numérico.

O perigo da conversão silenciosa

Não devemos afirmar que toda conversão incorreta ocorrerá sem emitir erro.

O CICS pode sinalizar condições como CCSIDERR, CODEPAGEERR e outros erros pertinentes.

Entretanto, também existem situações em que uma representação incorreta pode atravessar uma interface sem que a aplicação detecte a divergência semântica.

É por isso que precisamos validar o resultado final.

A regra fundamental

Dados de texto podem exigir conversão de caracteres. Dados binários não devem ser submetidos indiscriminadamente a essa conversão.

Uma estrutura que mistura campos textuais e COMP-3 não deve ser colocada inteira em um container CHAR com a expectativa de que o CICS descubra quais bytes precisam ser convertidos.

O mecanismo trata o conteúdo CHAR como dados de caracteres.

Ele não interpreta automaticamente um copybook COBOL para converter somente os campos textuais.


🏺 Capítulo VII — O container de cinco rostos: cada peça exige uma regra diferente

Vamos voltar aos cinco containers.

FIN-HEADER — A identidade da transação

Contém identificador e versão.

Pode ser representado como texto, desde que o contrato defina claramente sua codificação e seu formato.

Por exemplo:

V02|FIN-990217

A separação por delimitadores é apenas ilustrativa.

Uma implementação real deverá considerar escapes, comprimento e formatos definidos.

FIN-VALOR — O tesouro monetário

Contém um valor financeiro.

Se utilizar COMP-3, pode ser transportado como BIT, acompanhado de um contrato que defina precisão, escala, sinal e tamanho.

Uma alternativa seria representar o valor em um formato textual decimal explicitamente padronizado.

Nesse caso, a transformação deve ser feita pela aplicação, com validação numérica apropriada.

Os dois projetos são possíveis.

Não são intercambiáveis sem conversão.

FIN-CLIENTE — O nome que precisa continuar legível

Contém:

JOÃO GONÇALVES

É um candidato apropriado ao uso de CHAR.

O CCSID precisa corresponder à representação real.

O teste deve verificar os caracteres após a conversão e não apenas a ausência de erro técnico.

FIN-DOC — O documento que não pode ser traduzido como texto

Contém um comprovante binário.

Pode ser um PDF, por exemplo.

Seu conteúdo precisa permanecer binariamente íntegro durante o transporte.

Neste projeto, BIT é a escolha apropriada.

Se a aplicação alterar seus bytes indiscriminadamente, poderá tornar o documento inválido.

FIN-STATUS — O estado da operação

Contém um código ou uma descrição textual.

Por exemplo:

PENDING

APPROVED

REJECTED

O contrato precisa definir valores permitidos e seus significados.

Não basta converter os caracteres corretamente.

O programa também precisa interpretar corretamente a regra de negócio.

A conclusão

Cinco containers.

Cinco responsabilidades.

Duas categorias fundamentais de representação.

E uma exigência comum:

Cada conteúdo deve chegar ao consumidor com o significado preservado.


📏 Capítulo VIII — FLENGTH: quando o comprimento muda sem que ninguém altere o texto

O gerente encontra uma nova discrepância.

O nome do cliente foi transmitido corretamente.

Mas o comprimento em bytes mudou.

Como isso é possível?

Porque caracteres não ocupam necessariamente a mesma quantidade de bytes em todas as codificações.

Um exemplo simples

Considere:

JOÃO

Em uma codificação EBCDIC de byte único que represente esses caracteres, o texto pode ocupar quatro bytes.

Em UTF-8, o caractere à — ou o caractere acentuado correspondente, dependendo do texto efetivo — pode exigir mais de um byte.

No nome JOÃO, o caractere à ocupa dois bytes em UTF-8.

Assim, a sequência de quatro caracteres pode ocupar cinco bytes em UTF-8.

O texto não ganhou uma nova letra.

Mudou a codificação.

O papel de FLENGTH no PUT

Em PUT CONTAINER, FLENGTH indica o comprimento, em bytes, dos dados da área de origem.

Não deve ser interpretado simplesmente como quantidade de caracteres visíveis.

O papel de FLENGTH no GET

Em GET CONTAINER com INTO, o campo FLENGTH pode ser utilizado no controle do comprimento da área de destino e, na conclusão, informa o comprimento efetivamente retornado.

Se houver conversão, o comprimento depois da conversão pode ser diferente do original.

A consulta com NODATA

O CICS permite solicitar informações de comprimento sem copiar o conteúdo, utilizando NODATA.

Quando se pretende converter para um CCSID diferente, é importante especificar a codificação de destino também nessa consulta, para que o comprimento retornado corresponda aos dados convertidos.

O erro clássico

O programador descobre que o texto tem vinte caracteres.

Reserva vinte bytes.

Mas a codificação de destino exige mais bytes.

O resultado pode ser uma área insuficiente.

A lição

Comprimento em caracteres não é necessariamente comprimento em bytes.

Isso vale para UTF-8, para diversas codificações multibyte e para interfaces de integração que atravessam plataformas.


<WritingBlock id="76433" variant="document">## ☕ Capítulo IX — Java entra na tumba: strings, byte arrays e a API JCICS

O Banco de Mênfis possui um programa Java executado dentro do ambiente CICS.

A equipe utiliza a API JCICS para trabalhar com channels e containers.

É importante distinguir esse cenário de um serviço Java externo que se comunica por HTTP, MQ ou outra integração.

A API JCICS oferece objetos e métodos próprios para aplicações Java executadas sob CICS.

Strings Java

Uma string Java representa texto.

Quando esse texto é colocado em um container de caracteres por meio das interfaces apropriadas, o CICS pode realizar a conversão necessária.

Isso facilita a comunicação com programas COBOL que utilizam dados textuais em codificações suportadas.

Byte arrays

Um array byte[] representa uma sequência de bytes.

É adequado para transportar dados binários quando a interface e o container são utilizados de forma apropriada.

A documentação IBM diferencia explicitamente o tratamento de strings e dados binários na API de channels e containers.

O problema do BigDecimal

Imagine que o Java receba os oito bytes do campo COMP-3.

Não pode simplesmente executar uma conversão textual e esperar que o valor monetário apareça como uma representação decimal legível.

Packed decimal exige decodificação numérica específica.

A interpretação precisa conhecer:

A quantidade de dígitos.

A escala decimal.

O tratamento do sinal.

A validade da sequência.

E os limites de capacidade.

Depois dessa interpretação, a aplicação poderá representar o valor com um tipo decimal adequado, como BigDecimal, respeitando o contrato.

Uma alternativa arquitetural

O sistema também poderia transportar o valor monetário como texto decimal padronizado.

Por exemplo:

1250000000.00

Nesse caso, a aplicação COBOL teria de produzir essa representação corretamente.

O container poderia ser CHAR.

O Java precisaria interpretar a sequência como número decimal segundo um formato acordado.

A representação textual deve evitar ambiguidades de separador decimal, agrupamento e sinal.

Não é correto utilizar vírgulas e pontos conforme a configuração regional sem definir uma convenção de intercâmbio.

Qual das duas é melhor?

Depende dos requisitos.

Packed decimal em BIT pode preservar um formato legado com eficiência, mas obriga o consumidor a conhecer sua representação.

Texto decimal em CHAR pode oferecer maior interoperabilidade, mas exige conversão explícita e validação.

Uma representação de mensagem padronizada, com esquema, também pode ser considerada.

O essencial é manter o contrato explícito.


🕵️ Capítulo X — O erro que passou despercebido: o mesmo nome, duas codificações

O DBA apresenta as evidências da investigação fictícia.

O container FIN-CLIENTE havia sido criado como CHAR.

O programa emissor forneceu bytes textuais cuja codificação real não correspondia à indicação utilizada pela interface.

O Java recebeu o conteúdo.

Nenhum mecanismo poderia garantir a recuperação automática do significado correto a partir de uma identificação de codificação falsa.

O nome chegou incorreto.

Outro teste revelou que a equipe planejava transportar o comprovante PDF em um container de caracteres.

O documento ainda não havia sido alterado em produção, mas o desenho técnico apresentava risco.

Finalmente, o container FIN-VALOR utilizava uma estrutura COMP-3.

Esse conteúdo precisava de um contrato binário apropriado, e não de uma conversão genérica de caracteres.

A diferença entre três problemas

Problema de codificação: os bytes textuais são interpretados segundo o CCSID errado.

Problema de representação: bytes de um valor numérico são tratados como texto.

Problema de contrato: emissor e receptor discordam sobre os campos, versões ou significados.

Eles podem produzir sintomas semelhantes.

Mas exigem diagnósticos diferentes.

Por que o CICS não resolveu sozinho?

Porque o CICS oferece serviços de transporte e conversão dentro das regras configuradas.

Ele não conhece automaticamente a definição empresarial de cada campo.

Não sabe se um PDF deveria conter determinado texto.

Não decide se um valor monetário representa reais, dólares ou centavos.

Não conhece por si só o layout COMP-3 específico que uma aplicação criou.

Essas responsabilidades pertencem aos contratos e às aplicações.


🧪 Capítulo XI — Laboratório Bellacosa: testes para os cinco containers

Vamos construir um roteiro seguro de homologação.

O canal é:

FINCHAN

Os cinco containers possuem contratos definidos.

Teste 1 — Identificador e versão

Envie FIN-HEADER com um identificador conhecido.

Verifique se o Java recupera exatamente os caracteres esperados.

Confirme a versão.

Teste 2 — Valor monetário

Envie FIN-VALOR contendo um valor COMP-3 de oito bytes, dentro da capacidade definida.

Use BIT.

Valide os bytes recebidos e a interpretação numérica realizada pelo consumidor.

A operação de R$ 1,25 bilhão deve resultar exatamente no valor pretendido.

Teste 3 — Nome acentuado

Envie FIN-CLIENTE contendo:

JOÃO GONÇALVES

Verifique o CCSID declarado.

Confirme o nome após a conversão.

Não considere o teste aprovado apenas porque o container foi recebido.

Teste 4 — Documento binário

Envie FIN-DOC com um arquivo de teste, sem dados sensíveis.

Use BIT.

Compare o tamanho e um hash criptográfico adequado do conteúdo antes e depois do transporte.

Isso ajuda a identificar alterações inesperadas nos bytes.

Teste 5 — Status financeiro

Envie FIN-STATUS com um código reconhecido.

Teste também um código desconhecido.

O receptor deve rejeitar ou tratar explicitamente valores que não fazem parte do contrato.

Teste 6 — Container ausente

Não crie FIN-VALOR.

Verifique se o programa receptor detecta e trata a ausência, sem assumir valor zero.

Teste 7 — Comprimento inadequado

Envie um conteúdo diferente do tamanho exigido para a estrutura binária.

O receptor deve rejeitar a representação incompatível.

Teste 8 — CCSID incorreto

Em laboratório controlado, informe uma codificação que não corresponde aos bytes textuais reais.

Observe o comportamento.

O resultado pode variar conforme a conversão e os caracteres envolvidos.

Teste 9 — Reutilização do nome

Tente gravar conteúdos diferentes no mesmo container.

Valide o comportamento de substituição e as regras relativas ao DATATYPE já estabelecido.

Teste 10 — Carga e concorrência

Execute testes com várias tarefas e operações.

Confirme que os canais e containers são utilizados conforme seus escopos e que a aplicação não confunde dados de transações diferentes.

O que medir?

Comprimentos.

Codificações.

Identificadores.

Status.

Valores financeiros.

Integridade binária.

Condições de retorno.

Tempo de processamento.

O laboratório não deve validar apenas que todos os comandos foram executados.

Ele precisa demonstrar que o conteúdo recebido preservou o significado esperado.


🥚 Capítulo XII — Dez maldições do papiro das mil faces

Primeira maldição — A conversão que ninguém solicitou. Um container CHAR pode participar de conversão de caracteres, produzindo resultados inadequados quando o conteúdo foi classificado incorretamente.

Segunda maldição — O binário tratado como texto. COMP-3 e documentos PDF não devem ser submetidos a conversões genéricas de caracteres.

Terceira maldição — O CCSID falso. Declarar uma codificação diferente da real compromete a interpretação.

Quarta maldição — O comprimento antes e depois da conversão. Uma string pode ocupar quantidades diferentes de bytes nas codificações de origem e destino.

Quinta maldição — O container sobrescrito. Uma segunda escrita pode substituir o conteúdo anterior, conforme o comando e suas opções.

Sexta maldição — O nome diferente. FIN-CLIENTE e FIN-CLIENTES são contratos distintos quando usados como nomes de containers.

Sétima maldição — A versão esquecida. Um container pode transportar dados corretos para um contrato antigo e incorretos para um consumidor novo.

Oitava maldição — O Java que recebe bytes, mas espera uma string. O método utilizado precisa corresponder à natureza da informação.

Nona maldição — A falsa persistência. Containers de channel comuns não substituem automaticamente arquivos, bancos de dados ou mensageria recuperável.

Décima maldição — O sucesso técnico sem validação empresarial. Um LINK concluído não comprova que o valor de R$ 1,25 bilhão foi interpretado corretamente.


⚖️ Capítulo XIII — O julgamento de Thoth: quem mudou o rosto do tesouro?

O tribunal se reúne.

O especialista COBOL apresenta as estruturas originais.

O administrador CICS demonstra os comandos PUT e GET.

O desenvolvedor Java apresenta os métodos da API JCICS.

O responsável financeiro confirma o valor esperado.

O especialista de integração mostra os resultados de conversão.

Finalmente, a equipe identifica três falhas de projeto.

A primeira estava na indicação incorreta de codificação do texto.

A segunda estava na tentativa de tratar uma representação binária como caracteres.

A terceira estava na ausência de um contrato rigoroso para todos os containers.

A correção

FIN-HEADER passou a possuir um formato textual versionado.

FIN-VALOR recebeu uma representação financeira explicitamente definida e testada.

FIN-CLIENTE passou a utilizar a codificação declarada e validada.

FIN-DOC foi mantido como conteúdo binário.

FIN-STATUS passou a validar os códigos permitidos.

A equipe documentou os nomes, tamanhos, versões e tipos.

Os testes COBOL/Java foram ampliados.

E o processamento passou a confrontar os valores financeiros recebidos com os dados esperados do fluxo.

O veredito

O gerente pergunta:

— Então a culpa era dos containers?

O veterano responde:

— Não. Eles fizeram o trabalho para o qual foram concebidos. O problema estava na maneira como a aplicação descreveu e interpretou o conteúdo.

— Então o channel não garante a integridade de tudo?

— Ele oferece mecanismos de organização, transferência e conversão apropriados. A integridade empresarial depende também das regras aplicadas pelos participantes.

— E os cinco papiros?

— Cada um agora possui seu próprio contrato.

O gerente sorri.

— Finalmente o tesouro chegou ao destino certo?

— No nosso teste, sim. O valor foi interpretado corretamente, o nome foi preservado, o documento permaneceu íntegro e o status correspondeu ao processo.


☕ Epílogo — 03h17: o papiro recuperou seu verdadeiro rosto

O Banco de Mênfis conclui a homologação.

O COBOL envia os cinco containers.

O CICS executa o LINK.

O Java recebe os dados.

O nome do beneficiário aparece corretamente.

O documento binário conserva seus bytes.

O valor financeiro é interpretado segundo o contrato aprovado.

A transação fictícia de R$ 1,25 bilhão passa na conciliação do laboratório.

O gerente observa a imagem de Thoth.

— Afinal, qual era o segredo dos papiros?

O veterano responde:

— O escriba não precisava apenas preservar os símbolos. Era necessário preservar também as regras que permitiam compreendê-los.

— E isso vale para o CICS?

— Especialmente para o CICS.

— Por quê?

— Porque os dados podem atravessar programas COBOL, Java, APIs e outros ambientes. Cada fronteira precisa respeitar a representação e o significado da informação.

O veterano encerra a sessão.

No monitor aparece:

FINCHAN — CONTRACT VALIDATION PASSED

O relógio marca 03h17.

E ele escreve a conclusão:

O problema mais perigoso de uma integração não é quando os sistemas deixam de conversar. É quando continuam conversando, mas passam a atribuir significados diferentes aos mesmos dados.


🏺 A última lição do Mestre Jedi do Mainframe

Channels agrupam containers.

PUT CONTAINER grava os dados.

GET CONTAINER recupera os dados.

FLENGTH representa comprimentos em bytes envolvidos nessas operações.

CCSID identifica codificações de caracteres.

CHAR permite a conversão de caracteres segundo regras aplicáveis.

BIT preserva dados binários sem essa conversão.

A API JCICS permite que programas Java utilizem channels e containers no ambiente CICS.

Mas nenhuma dessas tecnologias elimina a necessidade de contratos de dados claros, versionados e validados.

Porque, no Papiro das Mil Faces, cada tesouro possuía sua própria linguagem. E somente aquele que respeitava a linguagem dos dados conseguia atravessar o templo sem transformá-los em outra coisa.

☕ Bellacosa Mainframe — Onde Thoth documenta os formatos, Tutancâmon protege o tesouro, Anúbis vigia os canais, Java conversa com COBOL e o CICS ensina que transportar bytes não é a mesma coisa que preservar significados.

📚 Referências técnicas oficiais IBM

A documentação IBM confirma as regras fundamentais deste episódio:

Vagner Renato Bellacosa, IBM Champion e especialista em IBM Mainframe
IBM Z17 SYSTEM ONLINE
Sobre o autor

Vagner Renato Bellacosa

IBM Champion 2026 • Especialista em IBM Mainframe

Vagner Renato Bellacosa trabalha com IBM Mainframe desde 1988 , é IBM Champion e especialista em COBOL, CICS, Db2, z/OS e IBM Z. Compartilha experiências profissionais, conhecimento técnico, história da computação e práticas do universo mainframe para aproximar novas gerações das tecnologias que sustentam empresas, bancos e governos ao redor do mundo.

IBM Champion IBM Z COBOL CICS Db2 z/OS Mainframe desde 1988
GitHub LinkedIn
Inicializando conteúdo...