Return Codes en z/OS: mecánica, control de flujo en JCL, comportamiento del TMP y casos especiales

En el ecosistema de z/OS, un código de retorno es más que un simple número de error. Es un contrato entre un componente invocado y quien lo llama: el componente informa cómo terminó, y quien lo llama decide qué hacer.

Este artículo describe la mecánica práctica de los Return Codes en z/OS, la forma en que interactúan con JCL, cómo la ejecución batch en TSO/E a través del Terminal Monitor Program (TMP) afecta a la propagación de los códigos de retorno, y por qué casos especiales como valores grandes, negativos, Language Environment y Return Codes de z/OS UNIX exigen un cuidado especial.

Definición arquitectónica y mecánica de funcionamiento

Un Return Code es un valor numérico devuelto por un programa, procesador de comandos, servicio del sistema, utilidad o job step para describir el resultado de una operación. El entorno que invoca ese componente puede entonces inspeccionar ese valor y decidir qué hacer a continuación.

Las interpretaciones típicas son:

Estos valores son comunes, pero no constituyen una ley universal. Muchas utilidades y servicios IBM usan una progresión de valores basada en múltiplos de cuatro, pero cada interfaz, subsistema, utilidad y entorno de programación puede definir sus propios significados para los códigos de retorno. Un valor de código de retorno solo es autoritativo cuando se interpreta en el contexto del componente que lo produjo.

Register 15 y la convención de enlace

A nivel del enlace entre programas, el software z/OS utiliza con frecuencia el register 15 del procesador (R15) en dos fases distintas de una llamada:

1. Al entrar en un programa o rutina invocada, R15 contiene con frecuencia la dirección del entry point.
2. Al regresar, R15 contiene normalmente el código de retorno suministrado al llamador.

En assembler, una rutina invocada devuelve típicamente el control a través del register 14, y el llamador inspecciona R15 para determinar el resultado. Esta es una convención de enlace IBM standard utilizada en muchas interfaces de llamada z/OS.

Múltiplos de cuatro: convención útil, no standard universal

El patrón conocido 0, 4, 8, 12 y 16 se utiliza ampliamente porque ofrece a operadores y autores de jobs batch una escala de severidad previsible. Sin embargo, los componentes z/OS también utilizan return codes fuera de este patrón. Algunas interfaces devuelven 20, 24 o valores superiores. Otras combinan un return code con un reason code. Algunos runtimes de lenguaje y utilidades imponen reglas adicionales de traducción.

Esto importa operativamente. Un RC=8 de una utilidad puede significar un problema de datos recuperable, mientras que otra utilidad puede usar RC=8 para señalar un error de sintaxis o un fallo de asignación. El código de retorno es una señal, no el diagnóstico final.

Integración con JCL y procesamiento de condiciones

En Job Control Language (JCL), los return codes son esenciales para determinar la ejecución condicional de flujos de trabajo. Un job step termina, el sistema registra un step completion code y los steps siguientes pueden probar ese código para decidir si deben ejecutarse o no.

Históricamente, esto se hacía mediante el parámetro COND. Más tarde, JCL introdujo las construcciones estructuradas IF/THEN/ELSE/ENDIF, que son más fáciles de leer y mantener. Ambos mecanismos siguen dependiendo de la información sobre la ejecución de los steps anteriores.

Control heredado: el parámetro COND

El parámetro COND controla si un step debe omitirse. Esta es la parte que a menudo confunde a quienes empiezan con JCL: una expresión COND verdadera significa no ejecutar este step.

Ejemplo:

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

Esto significa: comparar 4 con el código de retorno de STEP01. Si 4 < STEP01.RC es verdadero, STEP02 se omite.

Así, si STEP01 termina con RC=8, la expresión 4 < 8 evalúa a TRUE y STEP02 se omite.

Control moderno: IF/THEN/ELSE/ENDIF

El procesamiento condicional estructurado evita la lógica invertida de COND:

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

La definición es ahora más clara: ejecute el programa PROGB solo si el step anterior terminó con RC=0.

El procesamiento condicional en JCL es suficientemente potente para el control de flujo entre job steps, evaluando condiciones de job step y de estado de ejecución, como códigos de retorno, estado de ABEND y si un step llegó efectivamente a ejecutarse. Pero no está al nivel de las capacidades de un lenguaje de programación procedural genérico.

Ejecución batch en TSO/E y el Terminal Monitor Program

Cuando los return codes se producen en un entorno TSO/E, el comportamiento depende del entry point del Terminal Monitor Program (TMP) usado para ejecutar el comando o programa.

El TMP es el componente TSO/E que proporciona la interfaz entre el usuario, los procesadores de comandos y el programa de control TSO/E. Obtiene comandos, entrega el control a los procesadores de comandos y supervisa la ejecución de los comandos.

En una sesión interactiva de TSO/E, el TMP se invoca cuando se establece el entorno de la sesión. En TSO/E batch, normalmente se invoca a través de JCL. Un step típico de TSO/E batch tiene este aspecto:

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

El DDNAME SYSTSIN suministra comandos al TMP. SYSTSPRT recibe los datos de salida dirigidos al terminal.

IKJEFT01: el entry point batch tradicional del TMP

IKJEFT01 es el entry point clásico del TMP utilizado para ejecutar comandos TSO/E en background.

Su comportamiento respecto a los códigos de retorno es el siguiente:

• Si un comando o programa devuelve un código de retorno no nulo, IKJEFT01 guarda ese código y continúa procesando el siguiente comando.
• El código de retorno final presentado por el step queda efectivamente influido por el último comando procesado.
• Así, un código de retorno no nulo anterior puede ser sustituido u ocultado por un comando posterior.
• Si un comando o programa termina en ABEND, IKJEFT01 termina normalmente el job step y coloca RC=12 en el register 15.

El riesgo operativo es que un comando con fallo puede no determinar el código de retorno final del job step si comandos posteriores continúan y devuelven un código diferente.

IKJEFT1A: terminar con códigos no nulos devueltos directamente

IKJEFT1A cambia el comportamiento. Cuando un comando, programa o exec REXX invocado directamente devuelve un código de retorno no nulo, IKJEFT1A guarda ese código en R15 y termina.

Esto lo hace más adecuado cuando el control batch debe detenerse en el primer fallo detectado directamente.

Sin embargo, el comportamiento tiene límites importantes:

• Los códigos de retorno no nulos procedentes de CLISTs no afectan necesariamente a R15 de la misma manera.
• Los códigos de retorno de programas a los que IKJEFT1A no entregó control directamente pueden no propagarse como se espera.
• El comportamiento en caso de ABEND no consiste simplemente en “convertir todo a RC=12 o RC=16”.

Para ABENDs, IBM documenta comportamientos más específicos. Un system ABEND bajo IKJEFT1A puede hacer que el job step termine con system completion code X'04C', mientras que la información de finalización relevante se devuelve en R15. El tratamiento de user ABENDs también se basa en completion codes y no en una simple conversión a una escala de severidad.

IKJEFT1B: propagación más rigurosa de ABENDs

IKJEFT1B es todavía más riguroso. Igual que IKJEFT1A, termina cuando un comando, programa o exec REXX procesado directamente devuelve un código de retorno no nulo y guarda ese código en R15.

La principal diferencia operativa está en el comportamiento ante ABENDs. Si un comando o programa procesado por IKJEFT1B termina con system o user ABEND, el job step es forzado a terminar con system completion code X'04C', y el completion code del comando o programa se devuelve en R15.

Para jobs batch en producción, este comportamiento puede ser preferible porque hace más visible la terminación anormal para schedulers, automatización y equipos de operaciones.

Procedimientos de comandos: variables de código de retorno en CLIST y REXX

La visibilidad de los return codes dentro de procedimientos de comandos depende del lenguaje.

En CLISTs, &LASTCC contiene el código de retorno del último comando TSO/E, subcomando, CLIST anidado o instrucción CLIST.

En TSO/E REXX, la variable especial RC normalmente se define a partir del host command emitido más recientemente.

Códigos de retorno, ABENDs y completion codes

Un código de retorno y un ABEND son señales operativas relacionadas, pero no son lo mismo.

Un código de retorno normalmente significa que el programa alcanzó un punto de terminación controlado y devolvió un valor de estado a su llamador.

Un ABEND indica terminación anormal. Puede estar causado por un program check, una condición del sistema, un user ABEND explícito, una excepción de protección, un recurso ausente u otra condición que haya impedido la finalización normal.

En batch, tanto los códigos de retorno como los ABENDs influyen en el resultado del step, pero se representan de forma distinta. Un step puede terminar con un condition code como RC=8, o con un system o user completion code como S0C7, S013, U4038 u otro código de ABEND.

Esta distinción es esencial para la automatización. Probar solo códigos de retorno puede ignorar la semántica de terminación anormal; probar solo la ocurrencia de ABEND puede ignorar otras situaciones de fallo.

Casos especiales y curiosidades arquitectónicas

La regla de 4095: límites de los completion codes en JCL

En el procesamiento normal de condition codes en JCL, los valores de los códigos de retorno están limitados al intervalo 0 a 4095.

Cuando un programa devuelve un valor superior a 4095, z/OS usa la parte de orden inferior del valor para el step condition code. Se usan los tres dígitos hexadecimales más a la derecha, que después se convierten a decimal.

Ejemplo:

• Decimal 4096 es hexadecimal X'1000'.
• Los tres dígitos hexadecimales más a la derecha son X'000'.
• El return code del step que se reporta será, por tanto, 0.

Otro ejemplo:

• Decimal 5000 es hexadecimal X'1388'.
• Los tres dígitos hexadecimales más a la derecha son X'388'.
• X'388', lo que convertido a decimal da 904.
• El return code reportado por el step puede, por tanto, aparecer como RC=904.

La lección práctica es simple: procure evitar el uso de códigos de retorno aplicativos por encima de 4095 en procesamientos batch controlados por JCL.

Códigos de retorno negativos

Generalmente, un lenguaje de alto nivel soporta valores de retorno negativos. Por ejemplo, un programa C puede intentar devolver -1.

En un sistema en complemento a dos, -1 se representa con todos los bits a uno, o X'FFFFFFFF' en una representación de 32 bits. Si la lógica de condition code del job step usa los 12 bits de orden inferior, el valor pasa a ser X'FFF', que en decimal da 4095.

Así, un valor de retorno negativo a nivel del lenguaje de programación puede aparecer en JCL como un condition code con un valor positivo alto. Y esta es una de las razones por las que los programas batch en z/OS deben usar un intervalo de códigos de retorno no negativo y bien documentado.

R15: dirección del entry point a la entrada, código de retorno a la salida

R15 puede desempeñar dos papeles en el enlace standard:

• A la entrada, puede contener la dirección del entry point del programa llamado.
• A la salida, contiene normalmente el código de retorno.

Un programa assembler que no defina R15 antes de regresar puede, por tanto, devolver un valor no intencionado. Dependiendo del entorno de ejecución, ese valor puede interpretarse como un return code y después quedar restringido por las reglas de completion code en JCL.

El síntoma resultante puede ser un step return code extraño o aparentemente arbitrario.

Language Environment y códigos de retorno a nivel del lenguaje

Los programas modernos en COBOL, PL/I, C y C++ en z/OS se ejecutan con frecuencia bajo Language Environment (LE). LE establece un entorno de runtime, gestiona condiciones y participa en el procesamiento de terminación.

Un programa COBOL, por ejemplo, puede definir el registro especial RETURN-CODE. Un programa C puede devolver un valor desde main. Pero el valor a nivel del lenguaje de programación no siempre cuenta toda la historia. Las condiciones de runtime, la terminación anormal, las condiciones no tratadas y el procesamiento de terminación del LE pueden afectar a lo que el programa llamador o el sistema operativo acaban realmente viendo.

Considere el return code aplicativo como el resultado pretendido del programa, pero verifique cómo el entorno de runtime informa de ese resultado al programa llamador y al JCL, especialmente cuando se producen condiciones no tratadas o ABENDs.

Evite asumir que MOVE 0 TO RETURN-CODE o return 0; garantizan un step batch limpio si el runtime ha encontrado una condición seria no tratada.

z/OS UNIX, estado POSIX y BPXBATCH

z/OS UNIX System Services introduce otra capa de mapeo.

El procesamiento tradicional de condition codes en batch z/OS soporta valores hasta 4095. El exit status de POSIX es típicamente mucho más pequeño, y suele tratarse como un valor de 8 bits en el intervalo 0 a 255. La terminación mediante signal añade otra convención: valores 128 y superiores representan con frecuencia terminación por signal, obteniéndose el número de signal restando 128.

Cuando un job batch ejecuta trabajo UNIX a través de BPXBATCH, el return code final del step puede depender de variables de entorno, definiciones de spawn, decisiones de asignación y de la forma en que terminó el proceso UNIX.

Cuidados importantes:

• El exit status de UNIX puede no reflejarse directamente en el código de retorno de JCL.
• En algunos modos de BPXBATCH, los exit status pueden multiplicarse por 256 antes de dar origen al return code del batch step.
• La restricción del intervalo 0 a 4095 puede causar wraparound o valores inesperados.

Por ejemplo, un proceso UNIX que termine con status 3 puede observarse de forma diferente según el modo de ejecución de BPXBATCH y la configuración del entorno. En algunos casos documentados, un valor puede aparecer como 768, porque 3 * 256 = 768.

La lección práctica es que los códigos de retorno de BPXBATCH deben probarse en la configuración exacta utilizada en producción. No suponga una correspondencia uno a uno entre exit status POSIX y código de retorno en JCL que pueda aplicarse a todos los casos.

Orientaciones prácticas

Para programadores de aplicaciones:

• Use un conjunto pequeño y documentado de return codes.
• Prefiera valores convencionales como 0, 4, 8, 12 y 16, salvo que el contrato de llamada exija otra cosa.
• Evite valores de return code negativos.
• Evite valores por encima de 4095 en batch controlado por JCL.
• Documente si los return code indican avisos, errores recuperables, errores graves o fallos terminales.

Para autores de JCL:

• Prefiera IF/THEN/ELSE/ENDIF frente a expresiones COND complejas cuando la legibilidad sea importante.
• Recuerde la lógica invertida de COND: si la expresión es verdadera, el step se omite.
• Pruebe tanto resultados con código de retorno como resultados con ABEND.
• Tenga cuidado al ejecutar varios comandos TSO/E bajo el mismo step IKJEFT01, porque comandos posteriores pueden afectar al código de retorno final reportado.
• Use IKJEFT1A o IKJEFT1B cuando la semántica de terminación de esos entry points se ajuste mejor al requisito operativo.

Para equipos de operaciones y automatización:

• No trate todos los códigos de retorno no nulos de la misma forma.
• No trate RC=0 como señal determinante de éxito si los logs contienen fallos a nivel de aplicación.
• Distinga fallo controlado por return code de fallo por ABEND.
• Para workloads BPXBATCH y USS, valide el mapeo exacto de códigos de retorno en el entorno de producción.

8. Resumen

Los puntos esenciales que conviene retener son los siguientes:

• R15 transporta con frecuencia el return code del programa llamado en el enlace entre programas convencional.
• JCL examina la información de finalización de steps para controlar la ejecución siguiente.
• El patrón conocido 0, 4, 8, 12, 16 es una convención útil, no una regla universal.
• Entry points TMP como IKJEFT01, IKJEFT1A e IKJEFT1B difieren materialmente en la forma en que tratan return codes no nulos y ABENDs.
• Return codes y ABENDs son señales distintas y ambas tienen que considerarse en el control de producción.
• Return codes grandes, negativos, mediados por LE y derivados de USS/BPXBATCH pueden sorprender a autores de jobs batch, a menos que se prueben explícitamente.

Un entorno batch z/OS bien diseñado no se limita a verificar si un return code es cero. Define el significado de cada código de retorno, elige el wrapper de ejecución correcto y garantiza que JCL, schedulers, operadores y equipos de aplicaciones interpretan la señal de forma consistente.

Documentación útil

1. IBM, z/OS MVS Programming: Assembler Services Guide — convenciones standard de enlace entre programas, uso de registers y convenciones 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 — ejemplo de códigos de retorno específicos de un componente usando 0, 4, 8, 12 y 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 — procesamiento COND y ejecución condicional estructurada.

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

1. IBM, z/OS TSO/E Customization — comportamiento del Terminal Monitor Program y tratamiento de códigos de retorno y ABENDs en IKJEFT01, IKJEFT1A y IKJEFT1B.

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

1. IBM, z/OS TSO/E CLISTs — comportamiento de &LASTCC en el procesamiento CLIST.

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

1. IBM, z/OS TSO/E REXX Reference — variable especial RC en REXX y 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 de los tres dígitos hexadecimales más a la derecha para valores de código de retorno fuera del intervalo de JCL.

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

1. IBM, Enterprise COBOL for z/OS Language Reference — registro 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 — tratamiento de condiciones y terminación en 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 — comportamiento de los códigos de retorno en BPXBATCH y traducción de estados POSIX.

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