Return Codes no z/OS: mecânica, controlo de fluxo em JCL, comportamento do TMP e casos especiais

No ecossistema do z/OS, um código de retorno é mais do que um simples número de erro. É um contrato entre um componente invocado e o seu chamador: o componente informa como terminou, e o que chama decide o que fazer.

Este artigo descreve a mecânica prática dos Return Codes no z/OS, a forma como interagem com JCL, como a execução batch em TSO/E através do Terminal Monitor Program (TMP) afeta a propagação dos códigos de retorno, e porque é que casos especiais como valores grandes, negativos, Language Environment e Return Codes de z/OS UNIX que exigem cuidado especial.

Definição arquitetural e mecânica de funcionamento

Um Return Code é um valor numérico devolvido por um programa, processador de comandos, serviço de sistema, utilitário ou job step para descrever o resultado de uma operação. O ambiente que invoca esse componente pode então inspecionar esse valor e decidir o que fazer a seguir.

As interpretações típicas são:

Estes valores são comuns, mas não constituem lei universal. Muitos utilitários e serviços IBM usam uma progressão de valores baseada em múltiplos de quatro, mas cada interface, subsistema, utilitário e ambiente de programação pode definir os seus próprios significados para códigos de retorno. Um valor de código de retorno só é autoritativo quando interpretado no contexto do componente que o produziu.

Register 15 e a convenção de ligação

Ao nível da ligação entre programas, o software z/OS usa frequentemente o registo 15 do processador (R15) em duas fases diferentes de uma chamada:

1. À entrada de um programa ou rotina chamada, R15 contém frequentemente o endereço do entry point.
2. No regresso, R15 contém normalmente o código de retorno fornecido ao chamador.

No assembler, uma rotina chamada devolve tipicamente o controlo através do registo 14, e o chamador inspeciona R15 para determinar o resultado. Esta é uma convenção de ligação IBM standard usada em muitas interfaces de chamada z/OS.

Múltiplos de quatro: convenção útil, não standard universal

O padrão conhecido 0, 4, 8, 12 e 16 é amplamente usado porque dá aos operadores e aos autores de jobs batch uma escala de severidade previsível. No entanto, os componentes z/OS também usam return codes fora deste padrão. Algumas interfaces devolvem 20, 24 ou valores mais altos. Outras combinam um return code com um reason code. Alguns runtimes de linguagem e utilitários impõem regras adicionais de tradução.

Isto importa operacionalmente. Um RC=8 de um utilitário pode significar um problema de dados recuperável, enquanto outro utilitário pode usar RC=8 para sinalizar erro de sintaxe ou falha de alocação. O código de retorno é um sinal, não o diagnóstico final.

Integração com JCL e processamento de condições

Em Job Control Language (JCL), os return codes são essenciais para determinar a execução condicional de fluxos de trabalho. Um job step termina, o sistema regista um step completion code, e os steps seguintes podem testar esse código para decidir se devem ou não correr.

Historicamente, isto era feito através do parâmetro COND. Mais tarde, o JCL introduziu as construções estruturadas IF/THEN/ELSE/ENDIF, que são mais fáceis de ler e manter. Ambos os mecanismos continuam a depender de informação sobre a execução dos steps anteriores.

Controlo legado: o parâmetro COND

O parâmetro COND controla se um step deve ser ignorado. Esta é a parte que frequentemente confunde novos leitores de JCL: uma expressão COND verdadeira significa não executar este step.

Exemplo:

//STEP02  EXEC PGM=MYPROG,COND=(4,LT,STEP01)

Isto significa: comparar 4 com o código de retorno de STEP01. Se 4 < STEP01.RC for verdadeiro, STEP02 é ignorado.

Assim, se STEP01 terminar com RC=8, a expressão 4 < 8 avalia a TRUE e o STEP02 é ignorado.

Controlo moderno: IF/THEN/ELSE/ENDIF

O processamento condicional estruturado evita a lógica invertida do COND:

//STEP01   EXEC PGM=PROGA
//*
//TESTSTEP IF (STEP01.RC = 0) THEN
//STEP02   EXEC PGM=PROGB
//         ENDIF

A definição é agora mais clara: execute o programa PROGB apenas se o step anterior tiver terminado com RC=0.

O processamento condicional em JCL é suficientemente poderoso para controlo de fluxo entre job steps, avaliando condições de job step e de estado de execução, como códigos de retorno, estado de ABEND e se um step chegou efetivamente a correr. Mas não está ao mesmo nível das capacidades de uma linguagem de programação procedimental genérica.

Execução batch em TSO/E e o Terminal Monitor Program

Quando os return codes são produzidos num ambiente TSO/E, o comportamento depende do entry point do Terminal Monitor Program (TMP) usado para executar o comando ou programa.

O TMP é o componente TSO/E que fornece a interface entre o utilizador, os processadores de comandos e o programa de controlo TSO/E. Obtém comandos, entrega o controlo aos processadores de comandos e monitoriza a execução dos comandos.

Numa sessão interativa de TSO/E, o TMP é invocado quando é estabelecido o ambiente da sessão. Em TSO/E batch, é normalmente invocado através de JCL. Um step típico de TSO/E batch tem este aspeto:

//TSOSTEP  EXEC PGM=IKJEFT01
//SYSTSPRT DD  SYSOUT=*
//SYSTSIN  DD  *
  LISTCAT LEVEL(SOME.DATASET.PREFIX)
/*

O DDNAME SYSTSIN fornece comandos ao TMP. O SYSTSPRT recebe os dados de saída dirigidos ao terminal.

IKJEFT01: o entry point batch tradicional do TMP

IKJEFT01 é o entry point clássico do TMP usado para executar comandos TSO/E em background.

O seu comportamento em relação aos códigos de retorno é o seguinte:

• Se um comando ou programa devolver um código de retorno não nulo, IKJEFT01 guarda esse código e continua a processar o comando seguinte.
• O código de retorno final apresentado pelo step é efetivamente influenciado pelo último comando processado.
• Assim, um código de retorno não nulo mais cedo pode ser substituído ou ocultado por um comando posterior.
• Se um comando ou programa terminar em ABEND, IKJEFT01 termina normalmente o job step e coloca RC=12 no register 15.

O risco operacional é que um comando com falha pode não determinar o código de retorno final do job step se comandos posteriores continuarem e devolverem um código diferente.

IKJEFT1A: terminar com códigos não nulos devolvidos diretamente

IKJEFT1A altera o comportamento. Quando um comando, programa ou exec REXX invocado diretamente devolve um código de retorno não nulo, IKJEFT1A guarda esse código em R15 e termina.

Isto torna-o mais adequado quando o controlo batch deve parar à primeira falha detetada diretamente.

No entanto, o comportamento tem limites importantes:

• Códigos de retorno não nulos vindos de CLISTs não afetam necessariamente R15 da mesma forma.
• Códigos de retorno de programas a que IKJEFT1A não entregou controlo diretamente podem não ser propagados como esperado.
• O comportamento em caso de ABEND não é simplesmente “converter tudo para RC=12 ou RC=16”.

Para ABENDs, a IBM documenta comportamentos mais específicos. Um system ABEND sob IKJEFT1A pode fazer com que o job step termine com system completion code X'04C', enquanto a informação de conclusão relevante é devolvida em R15. O tratamento de user ABENDs também é baseado em completion codes e não numa simples conversão para uma escala de severidade.

IKJEFT1B: propagação mais rigorosa de ABENDs

IKJEFT1B é ainda mais rigoroso. Tal como IKJEFT1A, termina quando um comando, programa ou exec REXX processado diretamente devolve um código de retorno não nulo e guarda esse código em R15.

A principal diferença operacional está no comportamento perante ABENDs. Se um comando ou programa processado por IKJEFT1B terminar com system ou user ABEND, o job step é forçado a terminar com system completion code X'04C', e o completion code do comando ou programa é devolvido em R15.

Para job batch em produção, este comportamento pode ser preferível porque torna a terminação anormal mais visível para schedulers, automação e equipas de operações.

Procedimentos de comandos: variáveis de código de retorno em CLIST e REXX

A visibilidade dos return codes dentro de procedimentos de comandos depende da linguagem.

Em CLISTs, &LASTCC contém o código de retorno do último comando TSO/E, sub-comando, CLIST aninhado ou instrução CLIST.

Em TSO/E REXX, a variável especial RC é normalmente definida a partir do host command emitido mais recentemente.

Códigos de retorno, ABENDs e completion codes

Um código de retorno e um ABEND são sinais operacionais relacionados, mas não são a mesma coisa.

Um código de retorno significa normalmente que o programa atingiu um ponto de terminação controlado e devolveu um valor de estado ao seu chamador.

Um ABEND indica terminação anormal. Pode ser causado por um program check, condição de sistema, user ABEND explícito, exceção de proteção, recurso em falta ou outra condição que tenha impedido a conclusão normal.

No batch, tanto códigos de retorno como ABENDs influenciam o resultado do step, mas são representados de forma diferente. Um step pode terminar com um condition code como RC=8, ou com um system ou user completion code como S0C7, S013, U4038 ou outro código de ABEND.

Esta distinção é essencial para automação. Testar apenas códigos de retorno pode ignorar a semântica de terminação anormal; testar apenas a ocorrência de ABEND pode ignorar as outras situações de falha.

Casos especiais e curiosidades arquiteturais

A regra dos 4095: limites dos completion codes em JCL

No processamento normal de condition codes em JCL, os valores dos códigos de retorno estão limitados ao intervalo 0 até 4095.

Quando um programa devolve um valor superior a 4095, o z/OS usa a parte de ordem inferior do valor para o step condition code. Usam-se os três dígitos hexadecimais mais à direita, os quais são convertidos para decimal.

Exemplo:

• Decimal 4096 é hexadecimal X'1000'.
• Os três dígitos hexadecimais mais à direita são X'000'.
• O return code do step que é reportado será, portanto, 0.

Outro exemplo:

• Decimal 5000 é hexadecimal X'1388'.
• Os três dígitos hexadecimais mais à direita são X'388'.
• X'388', o que convertendo em decimal dá 904.
• O return code reportado pelo step pode, portanto, aparecer como RC=904.

A lição prática é simples: procure evitar a utilização de códigos de retorno aplicacionais acima de 4095 em processamentos batchL.

Códigos de retorno negativos

Geralmente, uma linguagem de alto nível suporta valores de retorno negativos. Por exemplo, um programa C pode tentar devolver -1.

Num sistema em complemento para dois, -1 é representado com todos os bits a um, ou X'FFFFFFFF' numa representação de 32 bits. Se a lógica de condition code do job step usar os 12 bits de ordem inferior, o valor torna-se X'FFF', que em decimal dará 4095.

Assim, um valor de retorno negativo ao nível da linguagem de programação, pode aparecer no JCL como um condition code com um valor positivo elevado. E esta é uma das razões pelas quais os programas batch em z/OS devem usar um intervalo de códigos de retorno não negativo e bem documentado.

R15: endereço do entry point à entrada, código de retorno à saída

R15 pode desempenhar dois papéis na ligação standard:

• À entrada, pode conter o endereço do entry point do programa chamado.
• À saída, contém normalmente o código de retorno.

Um programa assembler que não defina R15 antes de regressar pode, por isso, devolver um valor não intencional. Dependendo do ambiente de execução, esse valor pode ser interpretado como um return code e depois restringido pelas regras de completion code em JCL.

O sintoma resultante pode ser um step return code estranho ou aparentemente arbitrário.

Language Environment e códigos de retorno ao nível da linguagem

Programas modernos em COBOL, PL/I, C e C++ em z/OS correm frequentemente sob Language Environment (LE). O LE estabelece um ambiente de runtime, gere condições e participa no processamento de terminação.

Um programa COBOL, por exemplo, pode definir o registo especial RETURN-CODE. Um programa C pode devolver um valor a partir de main. Mas o valor ao nível da linguagem de programação nem sempre conta a história toda. Condições de runtime, terminação anormal, condições não tratadas e o processamento de terminação do LE podem afetar aquilo que o programa chamador ou o sistema operativo acabam realmente por ver.

Considere o return code aplicacional como o resultado pretendido do programa, mas verifique como o ambiente de runtime reporta esse resultado ao programa chamador e ao JCL, especialmente quando ocorrem condições não tratadas ou ABENDs.

Evite assumir que MOVE 0 TO RETURN-CODE ou return 0; garantem um step batch limpo se o runtime tiver encontrado uma condição séria não tratada.

z/OS UNIX, estado POSIX e BPXBATCH

O z/OS UNIX System Services introduz outra camada de mapeamento.

O processamento tradicional de condition codes em batch z/OS suporta valores até 4095. O exit status do POSIX é tipicamente muito mais pequeno, sendo geralmente tratado como um valor de 8 bits no intervalo 0 a 255. A terminação através de signal acrescenta outra convenção: valores 128 e acima representam frequentemente terminação por signal, obtendo-se o número do signal subtraindo 128.

Quando um job batch executa trabalho UNIX através de BPXBATCH, o return code final do step pode depender de variáveis de ambiente, definições de spawn, escolhas de alocação e da forma como o processo UNIX terminou.

Cuidados importantes:

• O exit status do UNIX pode não ser refletido diretamente no código de retorno do JCL.
• Em alguns modos de BPXBATCH, os exit status podem ser multiplicados por 256 antes de dar origem ao return code do batch step.
• A restrição do intervalo de 0 a 4095 pode causar wraparound ou valores inesperados.

Por exemplo, um processo UNIX que termine com status 3 pode ser observado de forma diferente dependendo do modo de execução de BPXBATCH e das definições do ambiente. Em alguns casos documentados, um valor pode aparecer como 768, porque 3 * 256 = 768.

A lição prática é que os códigos de retorno de BPXBATCH devem ser testados na configuração exata usada em produção. Não assuma uma correspondência um-para-um entre exit status POSIX e código de retorno em JCL que possa aplicar a todos os casos.

Orientações práticas

Para programadores de aplicações:

• Use um conjunto pequeno e documentado de return codes.
• Prefira valores convencionais como 0, 4, 8, 12 e 16, exceto se o contrato de chamada exigir outra coisa.
• Evite valores de return code negativos.
• Evite valores acima de 4095 em batch controlado por JCL.
• Documente se os return code indicam avisos, erros recuperáveis, erros graves ou falhas terminais.

Para autores de JCL:

• Prefira IF/THEN/ELSE/ENDIF a expressões COND complexas quando a legibilidade for importante.
• Lembre-se da lógica invertida do COND: se a expressão for verdadeira, o step é ignorado.
• Teste tanto resultados com código de retorno como resultados com ABEND.
• Tenha cuidado ao executar vários comandos TSO/E sob o mesmo step IKJEFT01, porque comandos posteriores podem afetar o código de retorno final reportado.
• Use IKJEFT1A ou IKJEFT1B quando a semântica de terminação desses entry points corresponder melhor ao requisito operacional.

Para equipas de operações e automação:

• Não trate todos os códigos de retorno não nulos da mesma forma.
• Não trate RC=0 como sinal determinante de sucesso se os logs contiverem falhas ao nível da aplicação.
• Distinga falha controlada por return code de falha por ABEND.
• Para workloads BPXBATCH e USS, valide o mapeamento exato de códigos de retorno no ambiente em produção.

8. Resumo

Os pontos essenciais a reter são os seguintes:

• R15 transporta frequentemente o return code do programa chamado na ligação entre programas convencional.
• O JCL examina a informação de conclusão de steps para controlar a execução seguinte.
• O padrão conhecido 0, 4, 8, 12, 16 é uma convenção útil, não uma regra universal.
• Entry points TMP como IKJEFT01, IKJEFT1A e IKJEFT1B diferem materialmente na forma como tratam return codes não nulos e ABENDs.
• Return codes e ABENDs são sinais diferentes e ambos têm de ser considerados no controlo em produção.
• Return codes grandes, negativos, mediados por LE e derivados de USS/BPXBATCH podem surpreender autores de jobs batch, a menos que sejam testados explicitamente.

Um ambiente batch z/OS bem desenhado não se limita a verificar se um return code é zero. Define o significado de cada código de retorno, escolhe o wrapper de execução certo e garante que JCL, schedulers, operadores e equipas de aplicações interpretam o sinal de forma consistente.

Documentação útil

1. IBM, z/OS MVS Programming: Assembler Services Guide — convenções standard de ligação entre programas, utilização de registers e convenções de retorno.

https://www.ibm.com/docs/en/zos/2.5.0?topic=program-registers

1. IBM, z/OS DFSMS Using Data Sets / OPEN return codes — exemplo de códigos de retorno específicos de um componente usando 0, 4, 8, 12 e 16.

https://www.ibm.com/docs/SSLTBW_3.1.0/com.ibm.zos.v3r1.idad500/x1cb.htm

1. IBM, z/OS MVS JCL Reference and JCL User's Guide — processamento COND e execução condicional estruturada.

https://www.ibm.com/docs/en/zos/3.1.0?topic=reference-jcl

1. IBM, z/OS TSO/E Customization — comportamento do Terminal Monitor Program e tratamento de códigos de retorno e ABENDs em IKJEFT01, IKJEFT1A e IKJEFT1B.

https://www.ibm.com/docs/SSLTBW_3.1.0/pdf/ikjb400_v3r1.pdf

1. IBM, z/OS TSO/E CLISTs — comportamento de &LASTCC no processamento CLIST.

https://www.ibm.com/docs/en/zos/2.5.0?topic=codes-lastcc

1. IBM, z/OS TSO/E REXX Reference — variável especial RC em REXX e códigos de retorno de host commands.

https://www.ibm.com/docs/SSLTBW_3.2.0/pdf/ikjc300_v3r2.pdf

1. IBM, z/OS TSO/E REXX Reference / IRXJCL return codes — uso documentado dos três dígitos hexadecimais mais à direita para valores de código de retorno fora do intervalo do JCL.

https://www.ibm.com/docs/en/zos/2.5.0?topic=ir-return-codes

1. IBM, Enterprise COBOL for z/OS Language Reference — registo especial RETURN-CODE.

https://www.ibm.com/docs/en/cobol-zos/6.4.0?topic=registers-return-code

1. IBM, z/OS Language Environment Programming Guide — tratamento de condições e terminação em LE.

https://www.ibm.com/docs/en/zos/3.1.0?topic=zos-language-environment-programming-guide

1. IBM, z/OS UNIX System Services User's Guide / BPXBATCH — comportamento dos códigos de retorno em BPXBATCH e tradução de estados POSIX.

https://www.ibm.com/docs/en/zos/3.2.0?topic=environments-bpxbatch