Ler JCL começa pela ordem de execução

JCL fica legível quando você para de tratá-lo como um programa e passa a vê-lo como um grafo de controle serializado. O fonte nomeia programas, fornece recursos e declara barreiras, mas vários sistemas decidem o que realmente executa: o conversor expande procedimentos, o catálogo resolve conjuntos de dados, JES e o initiator definem o contexto do job, o agendador pode injetar símbolos e um operador pode reiniciar o job no meio. Ler apenas os cartões visíveis é uma maneira fácil de desenhar um diagrama convincente e errado.

A primeira leitura tem um objetivo: recuperar as etapas ordenadas, os dados que cada uma lê e grava e as condições capazes de suprimi-la. Os detalhes de sintaxe vêm depois. Já vi equipes passarem uma manhã decifrando colunas e vírgulas sem perceber que um procedimento catalogado acrescentava seis etapas e o agendador selecionava a geração do dia anterior. Comece pelo comportamento e depois use a sintaxe para prová-lo.

Um membro JCL é um grafo de controle, não um script

Um job normalmente contém uma instrução JOB seguida por instruções EXEC, com instruções DD ligadas a cada EXEC. Isso parece sequencial e, no nível superior, é: sem salto, falha, reinício ou término anormal, JES apresenta as etapas ao initiator na ordem. Porém, o membro à sua frente pode conter apenas parte do grafo. Um EXEC pode invocar um procedimento catalogado ou inline, JCLLIB pode alterar onde os procedimentos são encontrados e INCLUDE pode trazer outras instruções antes da execução.

Separe quatro fases. Na entrada, JES lê o job e aplica regras de entrada. Na conversão, o sistema verifica JCL, expande procedimentos e resolve símbolos. Na alocação, z/OS localiza ou cria os conjuntos de dados e dispositivos necessários à etapa. Na execução, o programa escolhido roda e devolve um código ou termina de forma anormal. O processamento de saída e a limpeza cercam esse fluxo, mas não transformam JCL em lógica da aplicação.

Essa distinção explica um mistério comum: um job pode falhar antes de o primeiro programa executar. Um procedimento ausente, parâmetro simbólico não resolvido, nome duplicado de etapa, DD inválido ou conjunto de dados indisponível pode gerar erro JCL na conversão ou alocação. Não chame todo job vermelho de falha da aplicação. Primeiro pergunte se algum programa recebeu controle. As mensagens JES e o log do job respondem.

Faça um grafo aproximado antes de ler operandos. Desenhe um nó por etapa EXEC expandida, uma seta contínua para a sequência normal, uma tracejada para cada condição e arestas de dados para conjuntos nomeados que ligam produtores a consumidores. Anote três tipos de estado que não são arquivos comuns: símbolos resolvidos na conversão, estado do catálogo consultado na alocação e códigos de retorno produzidos na execução. O desenho revela depressa as evidências ausentes.

A ordem no fonte continua importante, mas responde apenas a uma pergunta: em que ordem as etapas elegíveis rodariam? Ela não diz se são elegíveis, em que um procedimento se expande, qual geração física um nome GDG relativo escolhe ou onde um reinício começa. Trate o membro como entrada de uma execução, não como a transcrição dela.

Instruções EXEC definem as unidades de trabalho

Cada EXEC cria uma etapa, e o operando informa se ela executa um programa diretamente ou chama um procedimento. EXEC PGM=IEFBR14 nomeia um programa. EXEC PROC=DAILY ou a forma curta EXEC DAILY chama um procedimento. O nome à esquerda de EXEC é a referência estável para condições, overrides, reinícios e mensagens; registre-o exatamente.

Comece com um exemplo compacto:

//BILLING  JOB (ACCT),'DAILY BILL',CLASS=A,MSGCLASS=X
//EXTRACT  EXEC PGM=EXTBILL,PARM='DAILY'
//INPUT    DD DSN=APP.CUST.MASTER,DISP=SHR
//OUT      DD DSN=APP.BILL.WORK(+1),DISP=(NEW,CATLG,DELETE),
//            SPACE=(CYL,(20,10)),UNIT=SYSDA
//SORT     EXEC PROC=SORTBILL,INDSN=APP.BILL.WORK(+1)
//LOAD     EXEC PGM=LOADBILL,COND=(0,NE,SORT)
//IN       DD DSN=APP.BILL.SORTED(+1),DISP=SHR

O contorno visível é EXTRACT, SORT, LOAD. Ainda não é um plano de execução. SORTBILL pode se expandir em várias etapas. SORT identifica a etapa chamadora, enquanto mensagens e condições internas usam nomes qualificados como SORT.COPY. LOAD tem uma condição que pode suprimi-lo. Os dois nomes relativos de geração precisam do contexto do catálogo.

Leia um EXEC nesta ordem: nome da etapa, PGM ou procedimento, controles de condição, limites de região ou tempo se existirem e texto de parâmetro passado ao programa. Não interprete PARM como lógica JCL. JCL passa o texto; só o contrato do programa explica PARM='DAILY'. O mesmo vale para SYSIN. Muitas vezes ele parece outra linguagem porque é outra linguagem, consumida por um utilitário, ferramenta de banco, compilador ou programa interno.

Um procedimento cria dois espaços de nomes. O job chamador tem uma etapa externa e o procedimento, etapas internas. Mensagens, overrides e sintaxe de reinício podem qualificá-las. Ao achatar o job, dê a cada etapa um nome como SORT.COPY e preserve o procedimento original ao lado. Senão, dois procedimentos com STEP1 parecerão a mesma etapa.

Programas também podem alocar dados dinamicamente por SVC 99 ou por uma biblioteca. Essas alocações não aparecem como DD no JCL submetido. Se um programa abre um conjunto que você não consegue explicar, examine mensagens, rastros de alocação, fonte ou configuração antes de concluir que falta um DD. JCL declara grande parte do ambiente, não necessariamente tudo.

Instruções DD ligam nomes do programa a recursos

Uma instrução DD pertence ao EXEC anterior até começar outro EXEC. O nome à esquerda normalmente é o nome que o programa abre; os operandos descrevem o recurso e seu ciclo de vida. Leia //INPUT DD DSN=APP.CUST.MASTER,DISP=SHR assim: nesta etapa, ligue o nome INPUT do programa ao conjunto catalogado e espere acesso compartilhado. INPUT não é uma variável que persiste entre etapas. Outra etapa pode definir seu próprio INPUT com outro sentido.

Classifique cada DD em cinco grupos práticos: conjunto catalogado, conjunto novo, conjunto temporário, dados inline ou saída do sistema. DSN= identifica um conjunto. DD * e DD DATA introduzem registros dentro do job. SYSOUT=* manda a saída para a classe do job. DUMMY faz muitos métodos de acesso agirem como se a entrada estivesse vazia ou a saída fosse descartada. Um DD ausente pode ser intencional se o programa aloca dinamicamente ou o trata como opcional; confirme no contrato.

DISP tem até três partes: status no início, ação após conclusão normal e ação após conclusão anormal. DISP=(NEW,CATLG,DELETE) solicita um conjunto novo, cataloga após fim normal e apaga após fim anormal. DISP=SHR solicita um conjunto existente com acesso compartilhado. OLD geralmente pede controle exclusivo, enquanto MOD posiciona para extensão e possui regras de criação que merecem consulta ao manual IBM. DISP descreve alocação e destino, não sucesso de negócio. Um programa pode retornar 8 normalmente, e a ação normal ainda vale porque não houve abend.

Nomes temporários começam com && e normalmente vivem durante o job. Passar um deles da etapa produtora para a consumidora cria uma aresta clara, embora o catálogo nunca o veja. Por outro lado, dois DSNs permanentes parecidos não provam relação. O agendador pode fornecer ambos, ou um job anterior pode ter criado a entrada.

Concatenação é outra armadilha visual. Instruções DD consecutivas podem formar uma única entrada lógica quando as posteriores omitem o ddname. Bibliotecas numa STEPLIB ou JOBLIB são pesquisadas na ordem, por isso o primeiro módulo correspondente vence. Entradas concatenadas são apresentadas em sequência, mas a compatibilidade depende do método de acesso e dos atributos. Registre a concatenação como uma ligação ordenada.

Overrides podem substituir ou acrescentar DD dentro de um procedimento. //SORT.COPYIN DD DSN=APP.SPECIAL.INPUT,DISP=SHR pode atingir COPYIN na etapa COPY sob a etapa chamadora SORT. O procedimento sozinho passa a descrever mal a execução, e o membro chamador parece ter um DD órfão. Só a expansão oferece a visão honesta.

A z/OS JCL Reference da IBM define operandos, mas não diz se seu programa exige um ddname nem quais registros pertencem a SYSIN. Procure a documentação de interface ou analise seu OPEN e alocação dinâmica. JCL explica a ligação; o programa explica o contrato. Misturar os dois produz migrações que mantêm nomes de arquivos e quebram comportamento.

A expansão de procedimentos revela o fonte ausente

Você não pode determinar a ordem até expandir todos os procedimentos e grupos INCLUDE com as mesmas bibliotecas e símbolos da execução. Um procedimento catalogado é JCL reutilizável guardado numa biblioteca. Um procedimento inline aparece entre PROC e PEND. Ambos podem conter EXEC, DD, parâmetros simbólicos e chamadas aninhadas dentro dos limites do sistema.

A listagem expandida na saída JES costuma ser evidência melhor que uma busca no repositório porque registra o resultado da conversão daquele envio. Procure a listagem JCL, em geral JESJCL, e mensagens em JESYSMSG e JESMSGLG. A configuração local muda retenção e exibição. Se a listagem e o Git divergem, verifique primeiro se o agendador enviou um membro gerado ou selecionou outra PROCLIB.

Parâmetros simbólicos usam formas como &INDSN.. O ponto pode encerrar o nome e desaparecer na substituição. Padrões ficam em PROC, chamadores os substituem em EXEC, SET atribui valores e o agendador pode substituir variáveis antes de JES ler o resultado. Preserve expressão e valor resolvido. Só o valor torna a próxima execução difícil de prever; só a fonte torna a execução observada impossível de explicar.

JCLLIB e concatenações locais controlam a busca. Duas bibliotecas podem conter um membro com o mesmo nome; a ordem decide qual se expande. É como uma versão de dependência codificada na ordem das bibliotecas em vez de um manifesto. Registre nome, biblioteca, nível de alteração disponível e instruções expandidas.

Overrides se aplicam depois da definição reutilizável. Podem alterar parâmetros EXEC, substituir ou anular DD e acrescentar ligações. Uma sintaxe curta pode esconder uma mudança grande de comportamento. Marque todo campo substituído no grafo achatado e cite os dois locais.

Não cole manualmente o texto dos procedimentos e declare a análise concluída. É fácil perder chamadas aninhadas, limites de símbolos, precedência de bibliotecas e overrides. Use a saída da conversão de uma execução registrada como base e reconstrua como ela surgiu. Muitas instalações usam TYPRUN=SCAN para verificar sintaxe, mas o efeito exato depende da política JES local. Um scan não prova dados da aplicação nem comportamento posterior.

Nomes GDG são resolvidos contra um catálogo mutável

Um generation data group é uma entrada de catálogo que gerencia uma sequência de conjuntos de gerações. Uma base como APP.BILL.WORK pode ser referida por nome absoluto ou número relativo: (0) para a geração atual, (-1) para a anterior e normalmente (+1) para uma nova. A forma relativa é prática na operação e incompleta na análise, pois o nome físico depende do catálogo.

Quando uma etapa cria APP.BILL.WORK(+1) com NEW e etapas seguintes leem a mesma geração relativa, o job pode passá-la adiante sem fixar o GxxxxVyy. O grafo deve mostrar a referência relativa e o nome absoluto observado. Nunca substitua todas as referências pelo que (0) significa hoje. O catálogo pode ter avançado desde a execução.

A falha difícil é um produtor pulado ou com erro seguido por um consumidor. Se EXTRACT aloca WORK(+1), termina anormalmente e DELETE se aplica, SORT não recebe uma nova geração válida. Conforme suas condições e o momento da alocação, pode ser pulado, falhar ao alocar ou encontrar outro estado do catálogo. Reiniciar apenas SORT depois pode fazer (+1) significar nova alocação em vez da saída pretendida. A sintaxe relativa não carrega linhagem.

Outra armadilha cruza jobs. O agendador pode rodar JOB A para criar uma geração e JOB B para consumir (0). A dependência não aparece em nenhum membro. Se JOB B começa cedo ou um operador repete JOB A, (0) pode escolher outra geração. Plano do agendador, histórico do catálogo e horários fazem parte do programa. O repositório não prova quais registros JOB B leu.

Monte um livro GDG para a execução com etapa, DD, referência relativa, disposição, DSN absoluto resolvido, ação no catálogo e resultado observado. Preencha com mensagens de alocação e evidência do catálogo, não inferência. Numa falha, registre se a alocação terminou e qual disposição ocorreu. Isso normalmente resolve se um reinício reutilizará dados ou criará outra geração.

A documentação IBM separa a base GDG, seu modelo e limite dos conjuntos de geração individuais. Preserve a distinção. Apagar ou descatalogar uma geração não altera a base, e sair pelo limite não significa apagamento imediato do volume. Para compreender o código, uma referência GDG relativa é uma consulta ao catálogo no contexto da execução, não um nome fixo.

Códigos de condição suprimem etapas com base em resultados anteriores

Um programa que termina normalmente fornece um código de retorno, mostrado como RC ou CC. JCL pode usá-lo para decidir se uma etapa posterior executa. Um código de abend difere de retorno normal, e uma falha de alocação ou conversão pode impedir qualquer código do programa. Mantenha RC, abend de sistema, abend de usuário e erro JCL em colunas separadas. Reduzi-los a sucesso ou falha destrói a informação necessária.

O antigo parâmetro COND é lido como teste de desvio. Em COND=(0,NE,SORT), o sistema compara o literal 0 ao RC de SORT com NE. Se forem diferentes, o teste é verdadeiro e a etapa atual é pulada. Em linguagem comum, LOAD só roda quando SORT retorna 0. Muitos invertem isso porque leem COND como condição para executar. Anote pular quando e depois traduza a comparação.

Alguns exemplos deixam a inversão clara:

• COND=(4,LT,COMPILE) significa pular quando 4 é menor que o RC de COMPILE, portanto valores acima de 4 suprimem a etapa.
• COND=(0,EQ,CHECK) significa pular quando CHECK retornou 0.
• COND=EVEN permite considerar a etapa mesmo após um abend anterior, sujeito às outras regras.
• COND=ONLY executa a etapa apenas após um abend anterior, ainda conforme o contexto completo.

JCL moderno admite IF, THEN, ELSE e ENDIF, que se parecem mais com lógica de aplicação. Expressões podem referir códigos qualificados e estado de abend. Ainda é controle em torno das etapas, não dentro dos programas. Aninhamento e qualificação podem estender um bloco além da tela; marque os limites no contorno expandido.

COND no job e na etapa interage com falhas, e um procedimento pode definir condições substituídas pelo chamador. Não reduza tudo a uma seta verde. Para cada etapa, escreva uma expressão de elegibilidade baseada em resultados anteriores e avalie com a execução real. Assim você separa caminhos possíveis do caminho ocorrido.

O significado do retorno pertence ao programa. RC 4 frequentemente indica aviso em utilitários IBM, mas um programa interno pode decidir outra coisa. Alguns agendadores aceitam uma faixa como sucesso, embora JCL distinga 0 de 4. Capture três políticas: o que o programa informa, o que JCL pula e o que o agendador classifica como sucesso. Um indicador não representa as três.

Um reinício muda o começo sem mudar o membro

Um job reiniciado não precisa começar no primeiro EXEC. O reinício pode nomear uma etapa do job ou uma etapa interna de procedimento; uma ferramenta local ou o agendador pode gerar a solicitação efetiva. O membro pode permanecer idêntico enquanto a execução começa no meio. Qualquer diagrama sem identidade da execução e metadados de reinício é provisório.

A segurança do reinício depende do estado dos dados, não apenas da ordem. Etapas anteriores podem ter catalogado saídas, atualizado banco, impresso registros, enviado mensagens ou confirmado checkpoints. Começar em STEP5 não desfaz esses efeitos. Por outro lado, DISP anormal pode ter apagado um conjunto necessário a STEP5. Antes de aprovar, liste todo efeito anterior e toda entrada exigida.

Um reinício por checkpoint dentro do programa difere do reinício de etapa JCL. Um utilitário pode continuar dentro de uma etapa, enquanto JES retorna numa fronteira EXEC. Evidências e regras de recuperação mudam. Se alguém diz que o job foi reiniciado, peça mecanismo, alvo e identificadores exatos.

Agendadores acrescentam outra camada invisível. Eles calculam datas, escolhem membros, injetam SET, adicionam dependências, seguram jobs por recursos e classificam retornos. Nada disso precisa aparecer no JCL armazenado. Um job anterior pode produzir o DSN lido pela primeira etapa visível. Uma regra de calendário pode escolher outro procedimento no fechamento do mês. Obtenha definição e registro de submissão do agendador junto com o spool.

O estado externo muda até uma repetição limpa. A geração GDG atual pode avançar, arquivos de entrada ser trocados, tabelas mudar e a ordem das bibliotecas expor nova versão. Uma repetição prova comportamento atual sob estado atual. Ela não reproduz a execução original sem preservar entradas, mapeamentos de catálogo, binários, símbolos e controles.

Operadores também emitem comandos e respondem a pedidos de alocação ou dispositivo. Essas ações raramente ficam no repositório. Log do job, logs de automação e ticket podem conter a aresta ausente. Se uma etapa esperou montagem de fita ou foi cancelada por tempo, só o fonte não explica duração ou status final.

O spool é evidência, não ruído

A maneira mais rápida de entender um batch herdado é combinar o fonte com um spool bem-sucedido e uma falha representativa. O fonte mostra possibilidades pretendidas. O spool mostra conversão, alocação, mensagens, retornos e o caminho de uma submissão real. Nenhum substitui o outro.

Comece por nome, job ID, sistema, hora de submissão, ordem ou run ID do agendador e se houve reinício. Depois reúna a listagem JCL convertida, mensagens JES e de sistema e SYSOUT da aplicação. JESJCL, JESMSGLG e JESYSMSG são nomes comuns, mas a política local varia. Preserve o material antes que a retenção o remova.

Leia em ordem cronológica e rotule as fases. Mensagens do conversor explicam símbolos e sintaxe. Mensagens de alocação ligam DD a conjuntos e volumes. Mensagens de término mostram programa, retorno e abend. Mensagens da aplicação explicam contagens e decisões. Horários podem enganar por buffering, por isso use também identidade de etapa e mensagem.

Para cada etapa expandida, registre uma linha observada:

SORT.COPY | PGM=SORT | ran=yes | RC=0004 | abend=none
  COPYIN  -> APP.BILL.WORK.G0123V00      DISP=SHR
  COPYOUT -> APP.BILL.SORTED.G0098V00   DISP=(NEW,CATLG,DELETE)
  gate    -> eligible after EXTRACT RC=0000

O formato é sem graça de propósito. Ele permite diff e obriga as incógnitas a aparecerem. Se o DSN absoluto estiver ausente, escreva desconhecido e identifique a evidência necessária. Não substitua silenciosamente o valor atual do catálogo.

Compare sucesso e falha por nome expandido, programa, DSNs resolvidos, símbolos, condições e resultados. A primeira diferença muitas vezes importa mais que o abend final. Outra geração de entrada pode causar validação posterior; uma STEPLIB alterada pode carregar outro código; um RC de aviso pode pular limpeza e contaminar a próxima execução.

Remova credenciais e dados regulados antes de mover spool para sistemas gerais de engenharia. JCL e SYSOUT podem conter campos de conta, tokens em PARM, controles de banco ou registros completos. Trate spool como evidência de produção. Numa revisão air-gapped, mantenha evidências e ferramentas dentro do perímetro do cliente.

Uma tabela de rastreamento torna a arqueologia revisável

A tabela deve permitir que outro engenheiro questione seu modelo sem reler todo o spool. Use uma linha por EXEC expandido, na ordem efetiva. As colunas mínimas são nome qualificado, programa, origem do procedimento, símbolos resolvidos, DDs de entrada e saída, regra de elegibilidade, RC ou abend observado e implicações de reinício. Acrescente alocações dinâmicas.

Siga esta sequência:

1. Congele fonte, registro do agendador, JCL expandido, spool e mapeamentos de catálogo de uma execução sob um run ID comum.
2. Expanda procedimentos e INCLUDE, resolva símbolos e atribua nome qualificado a cada EXEC.
3. Ligue DDs e concatenações a cada etapa e resolva GDGs para os nomes absolutos observados.
4. Traduza cada COND ou IF numa regra de elegibilidade e avalie contra os resultados registrados.
5. Marque início real, etapas puladas, alocações dinâmicas, ações de operador e efeitos importantes para reinício.

Revise a tabela em duas direções. De cima para baixo, confirme o controle. Siga cada conjunto do produtor aos consumidores para confirmar a linhagem. Um arquivo sem produtor pode ser feed externo, dependência do agendador ou estado antigo. Uma saída sem consumidor pode ser relatório, intercâmbio ou trabalho morto. Não apague antes de entender operação e retenção.

Separe fatos de hipóteses. SORT.COPY returned 4 é fato do spool. RC 4 means duplicate records é hipótese até os controles e mensagens de SORT provarem. APP.BILL.WORK(+1) resolvido como G0123V00 é evidência histórica. Dizer que um reinício repetirá o nome é previsão que exige análise de catálogo e reinício. Essa disciplina impede que uma história plausível vire especificação.

A tabela também revela a fronteira de migração. Programas, condições JCL, dependências do agendador, catálogo e ações de operadores juntos formam o batch. Traduzir COBOL ignorando JCL preserva apenas o componente visível. Um serviço moderno precisa de orquestração explícita, identidade durável de dados, regras de repetição e resultados observáveis compatíveis onde importa.

CodeHero lê junto todo o grafo COBOL e JCL e verifica o sistema reescrito contra tráfego de produção registrado com um harness de paridade. Uma migração linha a linha não recupera comportamento que vivia na seleção de procedimentos, ligações DD, estado GDG ou prática de reinício.

A modernização deve tornar explícita a ordem oculta

A modernização mais segura não reproduz cada instrução JCL em sintaxe nova. Ela preserva comportamento observável e transforma dependências implícitas em contratos nomeados e testáveis. Um conjunto temporário pode virar objeto ou tabela de staging, uma passagem GDG um artefato imutável da execução e uma condição COND uma transição explícita. O desenho pode mudar, mas testes de paridade precisam cobrir o comportamento do qual consumidores e operadores dependem.

Comece a especificação com execuções registradas, não com um diagrama de memória. Selecione caminhos normais, avisos, falhas de produtor, falhas de alocação e reinícios. Capture identidades de entrada, etapas expandidas, saídas, classes de retorno e efeitos externos. O tráfego de produção serve de evidência quando inclui mensagens e trocas que definem comportamento, sempre sob as restrições de segurança do cliente.

Não codifique peculiaridades acidentais cegamente. Alguns comportamentos são contratuais, outros dão suporte à operação e outros são defeitos invisíveis. Pergunte quais consumidores dependem de um detalhe e escreva um teste que nomeie a decisão. Se o sistema novo mudar a regra de propósito, registre a diferença aprovada em vez de enfraquecer a comparação.

Execução air-gapped pode ser necessária quando fonte, spool ou registros não podem sair do perímetro do cliente. Isso trata de implantação e dados; não implica certificação de conformidade. Separe essas afirmações em revisões e compras.

Um plano de transição confiável responde perguntas concretas: qual operação nova corresponde a cada etapa antiga, como fixar a identidade da entrada, como evitar efeitos duplicados em tentativas, como mapear avisos, como retomar uma execução parcial e qual evidência prova paridade. Se a equipe não responde, ainda não terminou de ler o JCL. Mais sintaxe não fechará a lacuna. Reconstrua uma execução inteira, inclusive tudo que o membro omitiu, e o batch deixará de parecer misterioso.