 |
| Bellacosa Mainframe e o yaml na pratica e sem misterios |
☕ Um Café no Bellacosa Mainframe
YAML na Prática sem Mistérios
O guia do Programador COBOL Padawan para dominar configurações, automação e infraestrutura sem provocar um ABEND na indentação
Imagine a seguinte cena.
Você passou anos navegando pelos corredores seguros do IBM Z. Conhece JCL, COBOL, CICS, Db2, VSAM, SDSF, RACF e talvez até tenha algumas cicatrizes de batalhas contra um S0C7 ocorrido às três da manhã.
Então, certo dia, alguém da equipe DevOps aparece e diz:
— Precisamos alterar o arquivo YAML do pipeline.
Você olha para a tela e encontra algo parecido com isto:
aplicacao:
nome: CONTAS
linguagem: COBOL
ambiente: homologacao
Não há IDENTIFICATION DIVISION.
Não há ponto final obrigatório.
Não há colunas 7, 8 ou 72.
Não há //SYSIN DD *.
Mesmo assim, aqueles espaços aparentemente inocentes controlam aplicações, pipelines, containers, provisionamento de infraestrutura e processos automatizados.
Bem-vindo ao universo do YAML.
Para o programador mainframe, aprender YAML não significa abandonar COBOL, JCL ou o IBM Z. Significa construir uma ponte entre o processamento corporativo tradicional e o mundo de automação, APIs, Git, CI/CD, Ansible, Kubernetes, z/OSMF, Zowe e infraestrutura como código.
O YAML pode parecer simples, mas possui uma regra implacável:
A máquina não enxerga beleza estética. Ela enxerga estrutura.
Um espaço colocado no lugar errado pode alterar completamente o significado do documento.
Pegue sua caneca de café, ajuste os sensores da Enterprise e prepare-se. Vamos explorar YAML do básico ao laboratório prático.
1. Afinal, o que é YAML?
YAML é uma linguagem de serialização de dados legível por humanos, muito utilizada para representar configurações e estruturas de informação.
A versão oficial da especificação é a YAML 1.2.2, publicada para corrigir erros e esclarecer pontos da versão 1.2, sem introduzir mudanças normativas fundamentais.
Serializar dados significa representar informações estruturadas em um formato que possa ser:
gravado em arquivo;
transmitido entre sistemas;
interpretado por programas;
armazenado em repositórios;
usado para configurar ferramentas;
convertido para objetos em diferentes linguagens.
A sigla YAML significa:
YAML Ain’t Markup Language
Ou, em português:
YAML não é uma linguagem de marcação.
Trata-se de um acrônimo recursivo, uma brincadeira clássica da cultura da computação.
Isso procura deixar claro que YAML não foi criado para formatar páginas como HTML. Seu objetivo principal é representar dados.
Um arquivo YAML pode descrever:
servidores;
aplicações;
ambientes;
parâmetros de execução;
pipelines;
inventários;
jobs;
containers;
permissões;
tarefas de automação;
configurações de testes;
serviços e dependências.
No universo mainframe, ele pode representar:
nomes de datasets;
subsistemas CICS;
regiões IMS;
bibliotecas de carga;
parâmetros de compilação;
aplicações COBOL;
ambientes de desenvolvimento;
comandos TSO;
tarefas do Ansible;
definições de pipelines;
informações de deploy;
configurações do Zowe;
chamadas ao z/OSMF;
propriedades usadas pelo IBM Dependency Based Build.
2. YAML não é uma linguagem de programação
Esse ponto é essencial.
YAML não possui, por si só:
comandos executáveis;
estruturas de repetição;
processamento de arquivos;
cálculos;
acesso a banco de dados;
chamadas de subprogramas;
controle transacional;
gerenciamento de memória.
Ele apenas descreve dados.
Considere:
programa:
nome: PGMPAG01
linguagem: COBOL
compilacao: obrigatoria
Esse documento não compila o programa.
Ele apenas declara informações.
Outra ferramenta poderá ler esse arquivo e decidir:
localizar o fonte PGMPAG01;
executar uma compilação;
realizar o bind do programa;
publicar o módulo de carga;
iniciar os testes.
Portanto, pense no YAML como um SYSIN moderno e estruturado.
No mainframe, é comum entregar parâmetros para um utilitário:
//SYSIN DD *
DELETE CLIENTES
DEFINE CLUSTER(...)
LISTCAT
/*
No mundo da automação, uma ferramenta pode receber parâmetros em YAML:
operacao: criar
dataset: USER01.TESTE.COBOL
tipo: biblioteca
formato:
recfm: FB
lrecl: 80
O princípio é parecido:
O arquivo descreve o que desejamos. Outra ferramenta interpreta e executa.
3. Onde um mainframer encontrará YAML?
YAML aparece com frequência crescente na modernização do IBM Z.
Ansible
Playbooks do Ansible são normalmente escritos em YAML.
- name: Verificar datasets
hosts: zos
tasks:
- name: Consultar biblioteca COBOL
ibm.ibm_zos_core.zos_data_set:
name: USER01.COBOL
state: present
Pipelines de CI/CD
GitHub Actions, GitLab CI, Azure DevOps e outras plataformas usam YAML para descrever pipelines.
jobs:
compilar:
steps:
- name: Compilar COBOL
run: python compilar.py
Kubernetes
Objetos como pods, deployments, services e configurações são frequentemente declarados em YAML.
Zowe
Arquivos de perfil e configurações de ferramentas do ecossistema Zowe podem envolver estruturas YAML.
IBM Dependency Based Build
Configurações de build e processos de automação podem utilizar YAML direta ou indiretamente, dependendo da arquitetura adotada.
Testes automatizados
Ferramentas podem usar YAML para definir:
massa de testes;
valores de entrada;
resultados esperados;
ambientes;
parâmetros de conexão.
Infraestrutura como código
YAML também aparece em ferramentas que provisionam, configuram ou descrevem ambientes de infraestrutura.
Por isso, conhecer YAML é como aprender a interpretar painéis de uma nave moderna. Você talvez não tenha construído o motor de dobra, mas precisa entender os controles.
4. O primeiro segredo: YAML é uma árvore
Um arquivo YAML deve ser imaginado como uma árvore hierárquica.
Veja:
aplicacao:
nome: PAGAMENTOS
plataforma: IBM Z
componentes:
- COBOL
- CICS
- Db2
A raiz possui uma chave chamada aplicacao.
Dentro dela existem:
nome;
plataforma;
componentes.
E componentes contém uma lista.
Podemos imaginar:
aplicacao
├── nome
├── plataforma
└── componentes
├── COBOL
├── CICS
└── Db2
Essa visão ajuda muito o programador COBOL.
Pense em uma estrutura semelhante a uma área de dados:
01 WS-APLICACAO.
05 WS-NOME PIC X(20).
05 WS-PLATAFORMA PIC X(10).
05 WS-COMPONENTES.
10 WS-COMPONENTE OCCURS 3 TIMES PIC X(10).
Não é uma correspondência perfeita, mas a analogia é excelente para começar.
5. Os componentes fundamentais
5.1 Chave e valor
A estrutura mais comum é:
chave: valor
Exemplo:
programa: PGMCAD01
linguagem: COBOL
O espaço depois dos dois-pontos é importante.
Prefira:
programa: PGMCAD01
Evite:
programa:PGMCAD01
5.2 Mapas
Um mapa agrupa pares de chave e valor.
programa:
nome: PGMCAD01
tipo: batch
linguagem: COBOL
programa contém um mapa com três propriedades.
Em COBOL, isso lembra um grupo de nível 01 com campos subordinados.
5.3 Listas
As listas são indicadas por hífens:
bibliotecas:
- USER01.COBOL
- USER01.COPYBOOK
- USER01.JCL
Isso se aproxima conceitualmente de uma tabela OCCURS.
05 WS-BIBLIOTECA OCCURS 3 TIMES PIC X(44).
5.4 Lista de objetos
Podemos ter vários elementos complexos:
programas:
- nome: PGMCAD01
tipo: batch
linguagem: COBOL
- nome: PGMCIC01
tipo: online
linguagem: COBOL
Cada item da lista possui suas próprias propriedades.
5.5 Booleanos
ativo: true
compilar: false
Para arquivos modernos, prefira true e false.
Evite depender de palavras como yes, no, on e off, pois bibliotecas baseadas em versões ou esquemas diferentes do YAML podem tratá-las de formas distintas.
Quando houver dúvida sobre o tipo, use aspas:
resposta: "yes"
estado: "on"
5.6 Números
timeout: 30
quantidade_retentida: 10
percentual: 99.5
5.7 Valores nulos
responsavel: null
Isso representa ausência de valor.
5.8 Comentários
# Aplicação responsável pelo cadastro de clientes
aplicacao: CLIENTES
Comentários começam com #.
Eles são úteis, mas não devem substituir uma documentação adequada.
6. A Lei Suprema da Indentação
Em COBOL tradicional, a coluna sempre teve grande importância.
YAML também é profundamente sensível ao posicionamento, porém usa indentação para representar hierarquia.
Observe:
aplicacao:
nome: FATURAMENTO
ambiente: producao
Os campos nome e ambiente pertencem a aplicacao.
Agora veja:
aplicacao:
nome: FATURAMENTO
ambiente: producao
Aqui, ambiente não pertence mais a aplicacao. Ele está no nível principal do documento.
O arquivo pode continuar sintaticamente válido, mas seu significado mudou.
Esse é um dos erros mais perigosos em YAML: o documento pode ser aceito pelo parser, mas representar outra estrutura.
Nunca use TAB para indentar
Use espaços.
A especificação do YAML trabalha com espaços na indentação, não com caracteres de tabulação.
Uma convenção segura é usar dois espaços por nível:
aplicacao:
banco:
nome: DB2P
tabelas:
- CLIENTES
- CONTAS
Não existe obrigação universal de usar exatamente dois espaços, mas a consistência é obrigatória.
É como trabalhar com níveis COBOL:
01 REGISTRO.
05 CLIENTE.
10 NOME.
10 CONTA.
O nível informa a estrutura. No YAML, a indentação cumpre esse papel.
7. Aspas: quando usar?
Muitos valores não precisam de aspas:
nome: FATURAMENTO
ambiente: producao
Entretanto, há situações nas quais as aspas evitam ambiguidades.
Strings que parecem números
codigo: "00123"
Sem aspas, um parser poderá tratar o valor como número e perder os zeros à esquerda.
Para um mainframer, isso é crítico. 00123 pode ser um código, não o número cento e vinte e três.
Datas
data_processamento: "2026-07-18"
Colocar datas entre aspas impede que determinadas bibliotecas façam conversões automáticas inesperadas.
Valores com caracteres especiais
descricao: "Processamento: fechamento mensal"
Valores semelhantes a booleanos
estado: "on"
resposta: "no"
Senhas ou tokens
Mesmo usando aspas, não grave segredos diretamente no YAML:
senha: "MinhaSenhaSecreta"
Isso continua sendo texto visível.
Aspas não criptografam.
O correto é usar:
gerenciadores de segredos;
variáveis de ambiente;
cofres de credenciais;
mecanismos protegidos pelo pipeline;
soluções corporativas integradas ao RACF ou à plataforma utilizada.
8. Textos com várias linhas
YAML possui recursos muito úteis para textos longos.
Preservando as quebras de linha com |
descricao: |
Este processo executa o fechamento diário.
Em caso de falha, consulte o runbook.
Não reinicie sem verificar o checkpoint.
O | preserva as quebras de linha.
Dobrando as linhas com >
descricao: >
Este processo executa o fechamento diário
e deve ser acompanhado pela equipe
responsável pela aplicação.
O > normalmente transforma as quebras em espaços, formando um parágrafo.
Isso pode ser útil para:
9. Laboratório no Windows
Vamos montar um ambiente prático.
Precisaremos de:
A documentação oficial do Python informa que o gerenciador de instalação para Windows pode ser obtido pela Microsoft Store ou pelos canais oficiais do Python.
A extensão YAML da Red Hat para Visual Studio Code oferece recursos como validação, detecção de erros, conclusão automática, visão estrutural do documento e suporte a esquemas.
Passo 1 — Criar a pasta do projeto
Abra o Prompt de Comando:
mkdir C:\yaml-mainframe
cd C:\yaml-mainframe
Essa será nossa USS local — uma pequena base de operações no Windows.
Passo 2 — Verificar o Python
Execute:
python --version
Em instalações mais novas do Windows, também poderá funcionar:
py --version
Depois, confirme o gerenciador de pacotes:
py -m pip --version
Passo 3 — Criar um ambiente virtual
No diretório do projeto:
py -m venv .venv
Ative o ambiente no Prompt de Comando:
.venv\Scripts\activate
No PowerShell:
.\.venv\Scripts\Activate.ps1
Quando o ambiente estiver ativo, o terminal normalmente exibirá algo semelhante a:
(.venv) C:\yaml-mainframe>
O ambiente virtual isola as dependências do projeto. Isso evita instalar bibliotecas globalmente sem necessidade.
Passo 4 — Instalar o PyYAML
python -m pip install pyyaml
PyYAML é uma biblioteca para ler e gerar YAML usando Python, e sua instalação pode ser realizada por meio do pip.
Passo 5 — Abrir o projeto no Visual Studio Code
code .
Caso o comando code não esteja disponível, abra o VS Code manualmente e selecione:
Arquivo → Abrir Pasta → C:\yaml-mainframe
Passo 6 — Instalar a extensão YAML
No VS Code:
abra a área de extensões;
pesquise por YAML;
selecione a extensão publicada pela Red Hat;
clique em instalar.
Agora teremos realce de sintaxe e auxílio na identificação de erros.
10. Nosso projeto: inventário de aplicações mainframe
Crie o arquivo:
inventario-mainframe.yaml
Digite:
---
empresa: Bellacosa Galactic Bank
ambiente: homologacao
responsavel: equipe-mainframe
zos:
sistema: ZOS1
versao: "3.1"
sysplex: BELLAPLEX
lpar: ZHML01
subsistemas:
cics:
ativo: true
regioes:
- nome: CICSHML1
tipo: AOR
porta: 30101
- nome: CICSHML2
tipo: TOR
porta: 30102
db2:
ativo: true
subsistema: DB2H
versao: "13"
databases:
- CLIENTES
- CONTAS
- PAGAMENTOS
aplicacoes:
- nome: CADASTRO-CLIENTES
codigo: "APL001"
tipo: online
linguagem: COBOL
transacao_cics: CCLI
programa_principal: PGMCIC01
bibliotecas:
fonte: USER01.COBOL
copybook: USER01.COPYLIB
carga: USER01.LOAD
dependencias:
- Db2
- CICS
- VSAM
compilacao:
obrigatoria: true
compilador: Enterprise COBOL
opcoes:
- RENT
- SSRANGE
- TEST
- nome: FECHAMENTO-DIARIO
codigo: "APL002"
tipo: batch
linguagem: COBOL
programa_principal: PGMFEC01
jcl: JOBFEC01
bibliotecas:
fonte: USER01.BATCH.COBOL
copybook: USER01.COPYLIB
carga: USER01.BATCH.LOAD
dependencias:
- Db2
- DFSORT
janela:
inicio: "22:00"
termino: "23:30"
compilacao:
obrigatoria: false
compilador: Enterprise COBOL
opcoes:
- RENT
- OPTFILE
politicas:
permitir_deploy_manual: false
exigir_aprovacao: true
reter_backups: 10
mensagem_operacional: |
Antes de executar qualquer deploy:
1. verificar o resultado da compilação;
2. conferir os testes automatizados;
3. validar o plano de retorno;
4. consultar o responsável pela mudança.
easter_egg:
nave: USS Enterprise
computador: LCARS-Z
mensagem: "A lógica é apenas o começo da sabedoria."
...
Agora vamos entender o documento.
11. Explicando cada parte
Marcador inicial
---
Os três hífens indicam o início de um documento YAML.
Não são sempre obrigatórios, mas tornam o arquivo mais explícito, especialmente quando existe mais de um documento no mesmo fluxo.
Informações gerais
empresa: Bellacosa Galactic Bank
ambiente: homologacao
responsavel: equipe-mainframe
São propriedades simples no nível raiz.
Estrutura do z/OS
zos:
sistema: ZOS1
versao: "3.1"
zos é um mapa.
A versão foi colocada entre aspas para preservar seu significado como identificador textual, não como número para cálculos.
Subsistemas
subsistemas:
cics:
db2:
Temos um mapa chamado subsistemas, contendo outros mapas.
Regiões CICS
regioes:
- nome: CICSHML1
tipo: AOR
regioes é uma lista.
Cada item possui:
Aplicações
aplicacoes:
- nome: CADASTRO-CLIENTES
aplicacoes é uma lista de objetos complexos.
Cada aplicação contém propriedades próprias.
Bibliotecas
bibliotecas:
fonte: USER01.COBOL
copybook: USER01.COPYLIB
carga: USER01.LOAD
Aqui usamos um mapa porque cada biblioteca possui uma função diferente.
Dependências
dependencias:
- Db2
- CICS
- VSAM
É uma lista simples.
Opções de compilação
opcoes:
- RENT
- SSRANGE
- TEST
Outro exemplo de lista.
Não estamos executando o compilador. Estamos documentando ou parametrizando quais opções uma automação deverá usar.
Mensagem operacional
mensagem_operacional: |
O símbolo | preserva as linhas, criando um pequeno runbook dentro do arquivo.
Final do documento
...
Os três pontos podem indicar o encerramento explícito do documento.
Assim como ---, são opcionais em muitos casos.
12. Criando o programa Python que lerá o YAML
Crie o arquivo:
ler_inventario.py
Digite:
from pathlib import Path
import sys
import yaml
ARQUIVO_YAML = Path("inventario-mainframe.yaml")
def carregar_yaml(caminho: Path) -> dict:
"""Carrega um arquivo YAML com tratamento básico de erros."""
if not caminho.exists():
raise FileNotFoundError(
f"O arquivo {caminho} não foi encontrado."
)
with caminho.open("r", encoding="utf-8") as arquivo:
dados = yaml.safe_load(arquivo)
if not isinstance(dados, dict):
raise ValueError(
"O documento YAML deve possuir um mapa no nível principal."
)
return dados
def validar_inventario(dados: dict) -> list[str]:
"""Verifica a presença de campos obrigatórios."""
erros = []
campos_obrigatorios = [
"empresa",
"ambiente",
"zos",
"aplicacoes",
]
for campo in campos_obrigatorios:
if campo not in dados:
erros.append(f"Campo obrigatório ausente: {campo}")
aplicacoes = dados.get("aplicacoes", [])
if not isinstance(aplicacoes, list):
erros.append("O campo 'aplicacoes' deve ser uma lista.")
return erros
for indice, aplicacao in enumerate(aplicacoes, start=1):
if not isinstance(aplicacao, dict):
erros.append(
f"A aplicação {indice} deve ser representada por um mapa."
)
continue
for campo in ["nome", "codigo", "tipo", "linguagem"]:
if campo not in aplicacao:
erros.append(
f"Aplicação {indice}: campo '{campo}' ausente."
)
return erros
def exibir_relatorio(dados: dict) -> None:
"""Apresenta um resumo legível do inventário."""
print("=" * 70)
print("INVENTÁRIO GALÁCTICO DE APLICAÇÕES MAINFRAME")
print("=" * 70)
print(f"Empresa........: {dados['empresa']}")
print(f"Ambiente.......: {dados['ambiente']}")
print(f"Sistema z/OS...: {dados['zos']['sistema']}")
print(f"Sysplex........: {dados['zos']['sysplex']}")
print(f"LPAR...........: {dados['zos']['lpar']}")
print()
aplicacoes = dados["aplicacoes"]
print(f"Aplicações encontradas: {len(aplicacoes)}")
print("-" * 70)
for aplicacao in aplicacoes:
print(f"Nome...........: {aplicacao['nome']}")
print(f"Código.........: {aplicacao['codigo']}")
print(f"Tipo...........: {aplicacao['tipo']}")
print(f"Linguagem......: {aplicacao['linguagem']}")
print(f"Programa.......: {aplicacao['programa_principal']}")
dependencias = aplicacao.get("dependencias", [])
print(f"Dependências...: {', '.join(dependencias)}")
opcoes = aplicacao.get("compilacao", {}).get("opcoes", [])
print(f"Opções COBOL...: {', '.join(opcoes)}")
print("-" * 70)
def main() -> int:
try:
dados = carregar_yaml(ARQUIVO_YAML)
erros = validar_inventario(dados)
if erros:
print("O inventário possui inconsistências:")
for erro in erros:
print(f"- {erro}")
return 8
exibir_relatorio(dados)
return 0
except yaml.YAMLError as erro:
print(f"Erro de sintaxe YAML: {erro}")
return 12
except (FileNotFoundError, ValueError, KeyError) as erro:
print(f"Erro ao processar inventário: {erro}")
return 16
if __name__ == "__main__":
sys.exit(main())
13. Por que usamos safe_load?
No código temos:
dados = yaml.safe_load(arquivo)
Essa escolha é muito importante.
Evite usar indiscriminadamente:
yaml.load(arquivo)
Alguns carregadores YAML podem interpretar tags capazes de criar objetos específicos da linguagem ou executar comportamentos indesejados.
Quando o arquivo vem de origem externa ou não confiável, o risco aumenta.
safe_load limita o carregamento a tipos básicos e seguros, como:
mapas;
listas;
strings;
números;
booleanos;
valores nulos.
É o equivalente a aplicar o princípio de menor privilégio:
Não entregue autoridade de sistema a um arquivo de configuração apenas porque sua extensão termina em .yaml.
14. Executando o laboratório
No terminal, com o ambiente virtual ativo:
python ler_inventario.py
O resultado deverá ser semelhante a:
======================================================================
INVENTÁRIO GALÁCTICO DE APLICAÇÕES MAINFRAME
======================================================================
Empresa........: Bellacosa Galactic Bank
Ambiente.......: homologacao
Sistema z/OS...: ZOS1
Sysplex........: BELLAPLEX
LPAR...........: ZHML01
Aplicações encontradas: 2
----------------------------------------------------------------------
Nome...........: CADASTRO-CLIENTES
Código.........: APL001
Tipo...........: online
Linguagem......: COBOL
Programa.......: PGMCIC01
Dependências...: Db2, CICS, VSAM
Opções COBOL...: RENT, SSRANGE, TEST
----------------------------------------------------------------------
Nome...........: FECHAMENTO-DIARIO
Código.........: APL002
Tipo...........: batch
Linguagem......: COBOL
Programa.......: PGMFEC01
Dependências...: Db2, DFSORT
Opções COBOL...: RENT, OPTFILE
----------------------------------------------------------------------
Parabéns.
Você acabou de:
criar um documento YAML;
representar um ambiente mainframe;
modelar aplicações batch e online;
descrever bibliotecas e dependências;
ler o documento com Python;
validar campos obrigatórios;
transformar dados declarativos em um relatório.
Isso já é a base de muitas automações reais.
15. Provocando um erro de propósito
Todo bom laboratório precisa de um Kobayashi Maru.
Altere:
aplicacoes:
- nome: CADASTRO-CLIENTES
Para:
aplicacoes:
- nome: CADASTRO-CLIENTES
codigo: "APL001"
Execute novamente:
python ler_inventario.py
O parser deverá informar um erro de sintaxe ou estrutura.
Agora teste um erro mais perigoso.
Remova o campo codigo de uma aplicação, mas mantenha a sintaxe válida:
- nome: CADASTRO-CLIENTES
tipo: online
linguagem: COBOL
Nesse caso, o parser consegue ler o YAML, porém nossa validação retorna algo semelhante a:
Aplicação 1: campo 'codigo' ausente.
Isso ensina uma diferença essencial:
Validação sintática
Pergunta:
O documento está escrito de maneira compreensível para o parser?
Validação semântica
Pergunta:
O documento contém os dados corretos para nossa aplicação?
Um YAML pode ser sintaticamente perfeito e operacionalmente inútil.
Da mesma forma, um JCL pode passar por determinadas validações e ainda apontar para o dataset errado.
16. YAML Schema: o copybook do YAML
À medida que os documentos crescem, validar tudo manualmente torna-se difícil.
É aí que entram os esquemas.
Um schema pode definir:
quais campos são obrigatórios;
quais tipos são permitidos;
quais valores são aceitos;
qual estrutura deve ser seguida;
quais propriedades são proibidas;
quais listas podem ficar vazias.
Para o mainframer, um schema funciona conceitualmente como uma combinação de:
copybook;
layout de arquivo;
contrato de interface;
regras de validação.
Sem schema:
porta: banana
O YAML é válido, pois banana é uma string.
Mas, se o sistema espera uma porta TCP numérica, o conteúdo está errado.
Com um schema, o editor poderá avisar:
A propriedade porta deve ser um número inteiro.
Esse recurso é especialmente importante em:
17. Anchors e aliases: o COPY do YAML
YAML possui anchors e aliases, que permitem reutilizar blocos.
Exemplo:
configuracao_padrao: &padrao_cobol
compilador: Enterprise COBOL
opcoes:
- RENT
- SSRANGE
- TEST
aplicacoes:
- nome: CLIENTES
compilacao: *padrao_cobol
- nome: CONTAS
compilacao: *padrao_cobol
O símbolo:
&padrao_cobol
cria uma âncora.
O símbolo:
*padrao_cobol
faz referência a ela.
É tentador pensar nisso como um COPY do COBOL.
Entretanto, tenha cuidado.
Anchors podem reduzir repetição, mas também tornar o documento mais difícil de entender. Algumas ferramentas possuem suporte parcial ou adotam comportamentos específicos.
Use anchors quando:
houver repetição significativa;
a equipe conhecer o recurso;
a ferramenta suportá-lo corretamente;
o ganho de manutenção superar a perda de clareza.
Não transforme seu YAML em um labirinto Klingon.
18. Boas práticas para mainframers
Use dois espaços por nível
aplicacao:
nome: CLIENTES
A consistência vale mais que a preferência individual.
Nunca use TAB
Configure o editor para substituir TAB por espaços.
Prefira nomes claros
Evite:
apl:
nm: CLI
tp: O
Prefira:
aplicacao:
nome: CLIENTES
tipo: online
Use uma convenção de nomes
Escolha um padrão:
programa_principal
ou:
programa-principal
Evite misturar:
programa_principal:
programa-principal:
ProgramaPrincipal:
Coloque códigos entre aspas
codigo: "000123"
Coloque horários entre aspas
inicio: "08:00"
Coloque datas entre aspas quando desejar tratá-las como texto
data: "2026-07-18"
Não grave segredos
Nunca faça:
usuario: ADMIN
senha: SENHA123
Valide antes do commit
O fluxo ideal é:
editar → validar → revisar → testar → commit → pipeline
Mantenha arquivos pequenos
Um YAML com milhares de linhas torna-se difícil de revisar.
Considere separar por:
ambiente;
aplicação;
domínio;
equipe;
finalidade.
Documente a intenção
# Ativada somente em homologação para testes de integração
simular_falha_db2: true
O comentário explica o motivo, não apenas repete o nome do campo.
Use controle de versão
Arquivos YAML devem ser armazenados no Git sempre que fizer sentido.
Assim você consegue saber:
19. Cuidados que evitam desastres
Um espaço pode mudar a hierarquia
Revise sempre o diff antes do commit.
Valores podem ser interpretados automaticamente
Quando o tipo for importante, use aspas ou schemas.
YAML válido não significa configuração válida
Teste com a ferramenta que realmente consumirá o arquivo.
Ambientes não devem compartilhar segredos
Produção, homologação e desenvolvimento precisam de separação adequada.
Copiar da internet exige revisão
Um exemplo encontrado em um fórum pode:
usar outra versão;
depender de outra ferramenta;
conter parâmetros obsoletos;
assumir permissões inexistentes;
expor credenciais;
executar ações destrutivas.
IA também pode errar a indentação
Um YAML gerado por inteligência artificial deve passar por:
Nunca envie um arquivo gerado automaticamente direto para produção.
Cuidado com comandos multilinha
Um comando embutido em YAML pode parecer correto, mas ser interpretado de forma diferente pelo shell.
Cuidado com duplicidade de chaves
Observe:
ambiente: teste
ambiente: producao
Dependendo da biblioteca, o segundo valor pode sobrescrever o primeiro sem o aviso esperado.
Para uma mudança de produção, isso pode ser desastroso.
Use validadores capazes de detectar chaves duplicadas.
20. Como evoluir depois deste laboratório
Depois de dominar este exemplo, o Programador COBOL Padawan pode avançar por uma trilha segura.
Nível 1 — Leitura
Aprenda a identificar:
mapas;
listas;
strings;
números;
booleanos;
valores nulos;
comentários;
hierarquia.
Nível 2 — Validação
Use:
extensão YAML no editor;
schemas;
linters;
scripts Python;
testes automatizados.
Nível 3 — Automação local
Crie scripts que leiam YAML para:
gerar JCL;
produzir relatórios;
montar parâmetros;
validar inventários;
criar documentação;
comparar ambientes.
Nível 4 — Git
Armazene arquivos em repositórios e pratique:
branch;
commit;
pull request;
diff;
revisão de código.
Nível 5 — CI/CD
Use YAML para criar pipelines de:
compilação;
testes;
análise estática;
empacotamento;
deploy;
rollback.
Nível 6 — Ansible para z/OS
Aprenda playbooks que possam:
Nível 7 — Infraestrutura declarativa
Explore ferramentas que transformam YAML em estado operacional.
Aqui ocorre uma mudança importante de mentalidade.
Em vez de dizer apenas:
Execute este comando.
Você passa a declarar:
Quero que o ambiente permaneça neste estado.
21. Comparando YAML, JCL, JSON e XML
YAML
Excelente para arquivos legíveis e configurações hierárquicas.
programa:
nome: PGMCAD01
tipo: batch
JSON
Muito usado em APIs e comunicação entre aplicações.
{
"programa": {
"nome": "PGMCAD01",
"tipo": "batch"
}
}
A estrutura de dados é semelhante, mas JSON exige mais sinais de pontuação.
XML
Possui tags de abertura e fechamento.
<programa>
<nome>PGMCAD01</nome>
<tipo>batch</tipo>
</programa>
É mais verboso, porém muito utilizado em integrações corporativas e sistemas legados.
JCL
Descreve a execução de trabalhos no z/OS:
//STEP01 EXEC PGM=PGMCAD01
//STEPLIB DD DSN=USER01.LOAD,DISP=SHR
YAML não substitui automaticamente o JCL.
Uma automação poderá ler YAML e gerar ou submeter JCL, mas o JES continuará precisando compreender o trabalho no formato adequado.
A ponte pode ser:
YAML
↓
Pipeline ou script
↓
JCL
↓
JES2
↓
Programa COBOL
22. Curiosidades para a tripulação
YAML nasceu para ser legível
Seu desenho privilegia estruturas que humanos possam editar com relativa facilidade.
JSON pode ser visto como um subconjunto estrutural do YAML 1.2
A compatibilidade com o modelo de dados do JSON foi um dos objetivos importantes da linha YAML 1.2.
A extensão preferida é .yaml
Também é comum encontrar:
.yml
Porém, .yaml é mais explícita.
YAML não é automaticamente simples
Documentos pequenos são agradáveis.
Documentos gigantes, com anchors, merges, múltiplos documentos e regras implícitas, podem tornar-se difíceis de manter.
Indentação é estrutura, não decoração
No COBOL, uma indentação visual ruim pode dificultar a leitura.
No YAML, uma indentação errada pode mudar o significado.
A melhor configuração é aquela que pode ser validada
Quanto mais crítica for a automação, menos você deve depender apenas da leitura humana.
23. Easter egg: o arquivo de missão da Enterprise
Crie:
missao-enterprise.yaml
---
nave:
nome: USS Enterprise
registro: NCC-1701
capitao: James T. Kirk
tripulacao:
- nome: Spock
funcao: ciencia
linguagem_preferida: YAML
- nome: Montgomery Scott
funcao: engenharia
linguagem_preferida: JCL
- nome: Nyota Uhura
funcao: comunicacoes
linguagem_preferida: JSON
missao:
destino: Sistema IBM Z
objetivo: modernizar_sem_destruir
diretriz_principal: |
Integrar o novo ao legado.
Preservar aquilo que funciona.
Automatizar aquilo que se repete.
Documentar aquilo que ninguém mais compreende.
alertas:
tab_encontrado: vermelho
segredo_no_repositorio: vermelho
deploy_sem_teste: vermelho
yaml_validado: verde
mensagem_final: >
Vida longa ao COBOL,
prosperidade ao mainframe
e atenção absoluta à indentação.
...
Observe o detalhe:
objetivo: modernizar_sem_destruir
Essa talvez seja a missão mais importante de toda modernização mainframe.
Modernizar não significa jogar fora décadas de regras de negócio.
Significa:
entender;
proteger;
documentar;
integrar;
automatizar;
evoluir.
24. Conclusão: o YAML como nova ponte do mainframe
YAML não substituirá o COBOL.
Não substituirá o JCL.
Não substituirá o CICS, o Db2, o IMS ou o z/OS.
Sua função é diferente.
YAML permite descrever configurações e intenções de uma forma que ferramentas modernas conseguem interpretar.
Para o mainframer, ele representa uma nova camada de comunicação entre:
o código COBOL;
os pipelines;
os repositórios Git;
os processos de build;
as ferramentas de automação;
os ambientes distribuídos;
a infraestrutura;
as equipes modernas de desenvolvimento.
O veterano que conhece COBOL possui uma vantagem enorme.
Ele já entende:
estruturas hierárquicas;
contratos de dados;
processamento previsível;
validação;
disciplina operacional;
ambientes controlados;
importância da compatibilidade;
consequências de um erro em produção.
Aprender YAML não é começar do zero.
É traduzir conhecimentos antigos para uma nova interface.
O programador que entende um copybook consegue compreender um schema.
Quem entende um SYSIN consegue compreender um arquivo declarativo.
Quem entende JCL consegue compreender pipelines.
Quem conhece PROC e parâmetros consegue compreender templates.
Quem respeita produção aprende rapidamente a respeitar indentação.
A verdadeira transformação não ocorre quando o mainframer abandona sua experiência.
Ela ocorre quando usa essa experiência para dominar novas ferramentas.
Portanto, abra o editor, crie seus primeiros arquivos, provoque erros em ambiente controlado, valide cada estrutura e coloque o YAML para trabalhar ao lado do COBOL.
Porque, no fim das contas, seja dentro de uma LPAR, de um container ou da USS Enterprise, uma regra continua universal:
Configuração sem validação é apenas um futuro incidente esperando sua janela de produção.
Vida longa ao COBOL.
Prosperidade ao IBM Z.
E que nenhum TAB clandestino atravesse os escudos da sua indentação.
