z/OSMF na prática: integrando COBOL, Python e JCL pelas APIs do mainframe
- Detalhes
Como enviar fontes, submeter jobs e consultar resultados sem perder os controles e os fundamentos do z/OS.
Editar um programa COBOL no computador, enviá-lo ao mainframe e acompanhar a compilação por um script Python é um exemplo concreto de integração entre ferramentas modernas e processamento tradicional. O código continua sendo compilado no ambiente adequado, o JCL continua definindo o trabalho e os controles de segurança continuam valendo. A diferença está na forma de conectar essas etapas.
No artigo “z/OSMF sem mistério: COBOL, APIs REST e a modernização do mainframe”, apresentamos essa visão. Neste complemento, vamos examinar o mecanismo: requisições HTTP, transferência de fontes, submissão de JCL e interpretação do resultado.
Os exemplos se baseiam na documentação da IBM indicada ao final. São didáticos e precisam ser adaptados e homologados na instalação. Não foram executados contra um servidor z/OS nesta preparação.
Um fluxo conhecido, agora acessível por API
O z/OSMF oferece serviços REST para arquivos, datasets e jobs. Uma aplicação externa pode utilizá-los sem automatizar teclas de um terminal. [1]
No cenário deste artigo, o desenvolvedor mantém um fonte local e um JCL de compilação previamente homologado no mainframe. A aplicação envia o fonte, submete esse JCL e consulta o resultado. Cada componente tem uma responsabilidade:
| Componente | Responsabilidade no cenário |
|---|---|
| Editor e Git | Edição e histórico do fonte |
| Cliente Python | Requisições HTTP e acompanhamento |
| z/OSMF | Acesso aos serviços de datasets e jobs |
| JES e infraestrutura batch do z/OS | Gerenciamento e execução do trabalho submetido |
| Compilador e binder | Compilação e ligação, conforme os passos do JCL |
| Gerenciador de segurança | Autorização sobre os recursos utilizados |
Essa divisão ajuda a localizar problemas. Uma falha de certificado acontece antes da compilação. Um erro no programa precisa ser investigado na listagem. Uma negativa de acesso ao spool envolve permissões, mesmo quando a submissão foi autorizada.
Antes da primeira chamada
O exercício pressupõe um z/OS com z/OSMF disponível por HTTPS, serviços de arquivos e jobs habilitados e um usuário autorizado. Também são necessários um dataset de fontes, o compilador e um JCL de compilação compatível com a instalação.
Usaremos nomes ilustrativos:
SEUHLQ.COBOL(OLAAPI): membro que receberá o fonte.SEUHLQ.JCL(COMPILA): JCL homologado que utiliza esse fonte.https://seu-host:porta: endereço do servidor, sem /zosmf ao final.
Procedures, bibliotecas, classes e parâmetros de compilação variam entre empresas. Por isso, utilizar um JCL existente e conhecido é o melhor ponto de partida. Trocar o nome do dataset em um exemplo da internet não torna uma compilação automaticamente compatível com o ambiente.
A documentação descreve autenticação básica, por certificados e por tokens, além de propagação de identidade em condições específicas. Aqui usamos autenticação básica sobre HTTPS apenas para simplificar o aprendizado, em uma instalação que permita esse método. [2]
Passo 1: enviar o fonte para um membro
Para escrever o conteúdo de um membro, a interface utiliza:
PUT /zosmf/restfiles/ds/SEUHLQ.COBOL(OLAAPI)
Content-Type: text/plain; charset=UTF-8
X-IBM-Data-Type: text;fileEncoding=IBM-1047
X-CSRF-ZOSMF-HEADER: cobol-dicasO corpo contém o fonte. O dataset particionado precisa existir; um membro ausente pode ser criado pela operação. O exemplo escolhe UTF-8 na transferência e IBM-1047 no destino. A página de códigos deve corresponder à instalação. [3]
Há uma diferença importante entre “arquivo de texto” e “fonte pronto para compilar”. No formato fixo, as posições têm significado. Confirme formato do fonte, comprimento dos registros e opções do compilador antes do envio. Quebrar automaticamente uma linha longa pode alterar o programa.
Em um membro compartilhado, obtenha o ETag na leitura e envie esse valor no cabeçalho If-Match da escrita. Se o recurso tiver mudado, a API pode responder 412, evitando a substituição de uma alteração concorrente. [3][4]
Para o primeiro exercício, prefira um membro exclusivo de desenvolvimento. O objetivo é aprender a integração sem misturar alterações de várias pessoas.
Passo 2: submeter um JCL já validado
A API permite indicar um membro que contém JCL:
PUT /zosmf/restjobs/jobs
Content-Type: application/json
X-CSRF-ZOSMF-HEADER: cobol-dicas
{
"file": "//'SEUHLQ.JCL(COMPILA)'"
}As barras e aspas fazem parte da sintaxe documentada para identificar o dataset totalmente qualificado. Uma submissão bem-sucedida retorna um documento JSON com informações como jobname e jobid. [5]
Esses identificadores precisam ser registrados. Eles permitem acompanhar o job correto, mesmo quando vários trabalhos possuem o mesmo nome.
Aceitar a submissão não equivale a aprovar a compilação. O processamento ainda pode aguardar execução, encontrar erro de JCL, terminar com código diferente de zero ou sofrer um abend.
Passo 3: acompanhar o job com Python
O exemplo abaixo submete o JCL existente, consulta seu estado e lista os arquivos de spool quando o job chega a OUTPUT. Ele não envia o fonte automaticamente: faça a etapa anterior de forma controlada antes de submeter.
Instale a dependência em um ambiente virtual Python:
python3 -m venv .venv
.venv/bin/python -m pip install requestsDefina os valores da sua instalação:
export ZOSMF_ORIGIN='https://seu-host:porta'
export ZOSMF_USER='SEUUSUARIO'
export ZOSMF_JCL='SEUHLQ.JCL(COMPILA)'
# Se necessário, informe o arquivo PEM da autoridade certificadora:
# export ZOSMF_CA_BUNDLE='/caminho/ca-corporativa.pem'Salve o trecho como acompanhar_job.py:
import os
import time
from getpass import getpass
from urllib.parse import quote, urlsplit
import requests
def main():
origin = os.environ["ZOSMF_ORIGIN"].rstrip("/")
parsed = urlsplit(origin)
if (parsed.scheme != "https" or not parsed.hostname
or parsed.username or parsed.password
or parsed.path or parsed.query or parsed.fragment):
raise ValueError("Informe somente https://host:porta.")
user = os.environ["ZOSMF_USER"]
jcl = os.environ["ZOSMF_JCL"]
with requests.Session() as session:
session.auth = (user, getpass("Senha z/OS: "))
session.verify = os.environ.get("ZOSMF_CA_BUNDLE") or True
session.headers.update({
"Accept": "application/json",
"X-CSRF-ZOSMF-HEADER": "cobol-dicas",
})
def call(method, path, **kwargs):
response = session.request(
method, origin + path,
timeout=(10, 30), allow_redirects=False, **kwargs
)
if 300 <= response.status_code < 400:
raise RuntimeError("Redirecionamento: confira a URL.")
response.raise_for_status()
return response
# Uma única tentativa de submissão: não repetir automaticamente.
submitted = call(
"PUT", "/zosmf/restjobs/jobs",
json={"file": f"//'{jcl}'"},
).json()
name = submitted["jobname"]
jobid = submitted["jobid"]
print(f"Submetido: {name}/{jobid}", flush=True)
path = ("/zosmf/restjobs/jobs/"
f"{quote(name, safe='')}/{quote(jobid, safe='')}")
deadline = time.monotonic() + 300
while time.monotonic() < deadline:
job = call("GET", path).json()
print("Estado:", job.get("status"),
"Retorno:", job.get("retcode"), flush=True)
if job.get("status") == "OUTPUT":
break
time.sleep(5)
else:
raise TimeoutError(
"Acompanhamento encerrado; o job não foi cancelado. "
f"Consulte {name}/{jobid} antes de submeter novamente."
)
for item in call("GET", path + "/files").json():
print("Spool:", item.get("id"), item.get("stepname"),
item.get("procstep"), item.get("ddname"))
# Critério conservador apenas para este exercício.
if job.get("retcode") != "CC 0000":
raise RuntimeError(
"Resultado exige análise de steps e spool; "
"o exercício só aprova CC 0000."
)
if __name__ == "__main__":
main()Execute com .venv/bin/python acompanhar_job.py.
O script mantém a validação TLS, solicita a senha sem gravá-la no fonte e limita o tempo de cada requisição. O cabeçalho de CSRF segue a orientação da IBM para clientes externos; uma aplicação Python não precisa da configuração de CORS exigida para determinados acessos entre origens no navegador. [2]
O acompanhamento tem uma janela aproximada de cinco minutos, além de eventuais chamadas em andamento. Encerrar essa espera não cancela o processamento remoto. Se o spool for removido antes da consulta, o script pode falhar ao localizar o job: ausência do recurso não comprova sucesso.
Passo 4: interpretar o resultado e ler o spool
Na consulta de estado, status e retcode respondem a perguntas diferentes. OUTPUT identifica o estado do job; o retorno informa como ele terminou. A interface também pode fornecer dados dos steps com step-data=Y. [6]
Um retorno CC 0000 é um sinal técnico favorável, mas testes funcionais ainda precisam verificar os resultados do programa. Para uma compilação real, a regra de aprovação deve considerar o compilador, o binder e os passos efetivamente executados. Códigos aceitos em uma etapa podem ser inadequados em outra. A documentação também prevê retornos como JCL ERROR, abends e falhas de segurança. [7]
Para investigar, liste os arquivos de spool e identifique o step, o procedure step e o DD desejados. A resposta contém seus identificadores. Um mesmo nome de DD pode aparecer em mais de uma etapa; evite escolher somente por SYSPRINT. [8]
A leitura usa:
GET /zosmf/restjobs/jobs/{jobname}/{jobid}/files/{id}/recordsSubstitua os campos pelos valores obtidos nas chamadas anteriores. A leitura depende das permissões sobre o spool. Em saídas grandes, use os mecanismos documentados de seleção de registros em vez de carregar tudo de uma vez. [9]
O cuidado que evita jobs duplicados
Uma falha de rede pode ocorrer depois que o servidor recebeu a submissão, mas antes de a resposta chegar ao cliente. Nesse caso, o job pode existir mesmo que o script tenha apresentado timeout.
Não configure repetição automática da submissão apenas porque o método utilizado é PUT. Para essa operação, uma nova chamada pode representar um novo job.
Como orientação de projeto, registre a intenção de submissão e a resposta obtida. Quando o resultado for incerto, reconcilie os jobs do usuário, o horário e os identificadores disponíveis antes de reenviar. O script didático evita retries automáticos, mas não implementa essa reconciliação.
Do exercício a uma automação confiável
Uma implantação real exige decisões adicionais. O fonte compilado deve corresponder à revisão registrada; bibliotecas compartilhadas podem permitir que uma alteração aconteça entre o envio e a compilação. Uma estratégia é usar áreas de build isoladas e registrar a revisão do Git junto dos identificadores do job.
Também é necessário definir credenciais apropriadas, controle de concorrência, retenção de saídas, tratamento de falhas e critérios de aprovação por etapa. O status do job deve virar evidência rastreável, e não apenas uma mensagem no terminal.
Essa é uma proposta de arquitetura de automação. As APIs fornecem operações; o processo de desenvolvimento precisa organizar quando utilizá-las e como interpretar suas respostas.
Onde entram Zowe, VS Code e outras linguagens
O Python torna as chamadas visíveis para fins didáticos. No dia a dia, o Zowe Explorer oferece integração de recursos do mainframe ao VS Code, enquanto outras ferramentas podem encapsular operações semelhantes. Os serviços disponíveis dependem da configuração da conexão e das extensões utilizadas. [10]
Um desenvolvedor Java ou JavaScript reconhece nesse fluxo elementos familiares: HTTPS, JSON, autenticação e tratamento de erros. Sua contribuição pode ser um cliente de integração, um painel interno ou uma etapa de pipeline. Para que funcione bem, precisará entender datasets, JCL, steps e spool.
O profissional COBOL contribui com o comportamento dos programas, as dependências e o significado dos resultados. A colaboração produz valor justamente porque integra essas competências.
O próximo passo é pequeno e verificável
Comece com a consulta de um job conhecido. Depois, leia uma saída. Em seguida, submeta um JCL simples homologado pela equipe. Só então avance para envio de fontes e compilação automatizada.
Esse percurso torna a modernização observável: cada etapa tem uma entrada, uma resposta e um resultado que pode ser conferido. O conhecimento de COBOL e JCL passa a ser utilizado também por ferramentas e processos acessíveis a outras comunidades de desenvolvimento.
Você já utiliza z/OSMF ou Zowe no trabalho? Compartilhe sua experiência e suas dúvidas no fórum do COBOL Dicas. Conheça também o COBOL Dicas LAB e suas ferramentas de apoio ao aprendizado.
COBOL Dicas — do básico ao avançado, sem mistério. 🦖
Referências técnicas
Pesquisa documental: 26 de setembro de 2026. Confira a documentação correspondente à versão e à manutenção da sua instalação.
