Python en z/OS: enviar jobs desde un script y recibir el resultado en Microsoft Teams
Esta entrada sigue la serie de Python en z/OS: pySDSF en z/OS 3.2: vigilar el spool y avisar por Microsoft Teams, Crear usuario para scripts Python en batch (RACF) y Python en z/OS: entorno virtual (venv y pyproject.toml).
Hasta ahora, los scripts leían información de SDSF. En esta entrada damos un paso más: un script que construye un job, lo envía a JES, espera a que termine, muestra su salida y avisa por Microsoft Teams de si ha ido bien o no. Todo en z/OS 3.2 (stock image), con el usuario PYBATCH y su entorno virtual.
Esto es útil cuando el JCL depende de datos que calcula el script (un prefijo, una fecha, una lista de data sets) o cuando un proceso tiene que lanzar un job y actuar según cómo termine.
Cómo enviar un job desde z/OS UNIX
📖 submit - Submit a batch job for background processing
z/OS UNIX tiene el comando submit, que envía un fichero con JCL a JES y escribe el ID del job. El JCL tiene que llevar su ficha JOB: sin ella, submit falla. Compruebo que está disponible en OMVS:
type submitsubmit is cached /bin/submit
Otra forma de hacerlo es con ZOAU (IBM Z Open Automation Utilities), que tiene una API de Python para trabajar con jobs y data sets. En la stock image está instalado en /usr/lpp/IBM/zoautil (versión 1.4.1.0). Aquí uso submit porque viene con z/OS UNIX y no necesita nada más instalado, y pySDSF, que ya tenemos en el entorno virtual de PYBATCH, para esperar al job y leer su salida.

El script
El script, submit_job.py, hace cinco cosas:
- Construye un job a partir de una plantilla: un LISTCAT del prefijo que recibe como argumento (IBMUSER si no recibe ninguno).
- Lo envía con
submity se queda con el ID del job. - Con pySDSF, mira el panel ST cada 5 segundos hasta que el job está en la cola de salida (PRINT), con un máximo de 120 segundos.
- Muestra el código de retorno y toda la salida del job.
- Manda una tarjeta a Microsoft Teams con el resultado: OK si el job terminó con CC 0000 y FAILED si no. Y termina con 0 o con 8, según el resultado.
#!/usr/bin/env python3
"""Build a job from a template, submit it and wait for its result with pySDSF."""
import os
import re
import subprocess
import sys
import tempfile
import time
from string import Template
from pysdsf import Connection
from pysdsf.isfexception import ISFException
from spool_alert import post_to_teams
JOBNAME = "PYLISTC"
WAIT_SECONDS = 120
MAX_CC = 0 # highest condition code that counts as a success
# $hlq is replaced by the script; everything else is plain JCL
JCL = Template("""\
//PYLISTC JOB (ACCT),'LISTCAT',CLASS=A,MSGCLASS=X
//* Job built and submitted by submit_job.py
//LIST EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
LISTCAT LEVEL($hlq)
/*
""")
HLQ_PATTERN = re.compile(r"[A-Z@#$][A-Z0-9@#$]{0,7}(\.[A-Z@#$][A-Z0-9@#$]{0,7})*")
def submit(jcl):
"""Write the JCL to a temporary file in EBCDIC, submit it and return the job ID."""
with tempfile.NamedTemporaryFile("w", encoding="cp1047", suffix=".jcl",
delete=False) as jcl_file:
jcl_file.write(jcl)
path = jcl_file.name
try:
subprocess.run(["chtag", "-tc", "IBM-1047", path], check=True)
result = subprocess.run(["submit", path], capture_output=True, text=True)
finally:
os.remove(path)
output = result.stdout + result.stderr
match = re.search(r"\b(JOB\d{5}|J\d{7})\b", output)
if result.returncode != 0 or not match:
raise RuntimeError(f"submit failed (rc {result.returncode}):\n{output}")
return match.group(1)
def wait_for_job(connection, jobname, jobid):
"""Poll SDSF ST until the job is on the output queue. Returns (result, row)."""
deadline = time.time() + WAIT_SECONDS
while time.time() < deadline:
jobs = connection.status_of_jobs(prefix=jobname, owner="*",
columns=["JNAME", "JOBID", "QUEUE", "RETCODE"])
for row in jobs:
if row["JOBID"] == jobid and str(row["QUEUE"]).strip() == "PRINT":
return jobs, row
time.sleep(5)
raise TimeoutError(f"{jobname}({jobid}) did not end in {WAIT_SECONDS} seconds")
def main():
url = os.environ.get("TEAMS_WEBHOOK_URL")
if not url:
sys.exit("TEAMS_WEBHOOK_URL is not set")
hlq = (sys.argv[1] if len(sys.argv) > 1 else "IBMUSER").upper()
if not HLQ_PATTERN.fullmatch(hlq):
sys.exit(f"Not a valid data set prefix: {hlq}")
jobid = submit(JCL.substitute(hlq=hlq))
print(f"Submitted {JOBNAME}({jobid}) for LISTCAT LEVEL({hlq})")
connection = Connection()
try:
jobs, row = wait_for_job(connection, JOBNAME, jobid)
retcode = str(row["RETCODE"]).strip()
print(f"{JOBNAME}({jobid}) ended: {retcode}")
for line in jobs.browse(row):
print(line)
except TimeoutError:
retcode = f"not ended after {WAIT_SECONDS} seconds"
print(f"{JOBNAME}({jobid}) {retcode}")
except ISFException as e:
sys.exit(f"SDSF error: {e}")
finally:
connection.close()
# "CC 0000" up to MAX_CC is a success; ABEND, JCL ERROR or a timeout is not
match = re.fullmatch(r"CC (\d+)", retcode)
ok = bool(match) and int(match.group(1)) <= MAX_CC
result = "OK" if ok else "FAILED"
status = post_to_teams(url, f"{os.uname().nodename}: {JOBNAME}({jobid}) {result}",
[f"LISTCAT LEVEL({hlq})", f"Return code: {retcode}"])
print(f"{result}: Teams answered HTTP {status}")
return 0 if ok else 8
if __name__ == "__main__":
sys.exit(main())Paso a paso:
La plantilla del job
El JCL está en el script como texto, con Template de la librería estándar de Python. Lo único que cambia es $hlq, que substitute() sustituye por el prefijo. El resto es JCL normal, con sus columnas, como si estuviera en un miembro.
Ojo con el símbolo $: en una plantilla, cualquier $ que sea parte del JCL (por ejemplo, un data set con $ en el nombre) hay que escribirlo $$. Si no, substitute() falla o lo sustituye.
El nombre del job está en dos sitios: en JOBNAME, que es el que el script busca en SDSF, y en la ficha JOB de la plantilla. Si se cambia, hay que cambiarlo en los dos.
Antes de meter el prefijo en el JCL, el script lo comprueba con una expresión regular: uno o varios cualificadores de hasta 8 caracteres, que empiezan por letra o por @, # o $. Si el argumento no cumple, el script termina sin enviar nada. Así nadie puede colar líneas de JCL a través del argumento.
Enviarlo con submit
- El JCL se escribe en un fichero temporal de
/tmp. Para no depender de conversiones, lo escribo directamente en EBCDIC (encoding="cp1047") y lo etiqueto conchtag -tc IBM-1047. subprocess.runlanzasubmitcon ese fichero y recoge lo que escribe.- El ID del job se busca en esa salida con una expresión regular. En mi sistema tiene la forma
JOBnnnnn(por ejemplo, JOB05055). Si el rango de números de job de JES2 (JOBDEF RANGE) pasa de 99999, los IDs nuevos cambian aJnnnnnnn; la expresión regular acepta las dos formas. - El fichero temporal se borra siempre, haya ido bien o no (
finally). - Si
submitfalla o no aparece el ID, el script termina con el error y lo que escribiósubmit.
Esperar a que termine
status_of_jobs() es el panel ST de SDSF, como en la entrada de pySDSF. Le pido solo el nombre, el ID, la cola y el código de retorno (QUEUE y RETCODE, los nombres internos de SDSF). Un job que ha terminado pasa a la cola PRINT; mientras está en ejecución, está en EXECUTION. El script repite la consulta cada 5 segundos. Si a los 120 segundos el job no ha terminado, deja de esperar y lo da como fallido, con su aviso en Teams. El job no se cancela: sigue en el sistema y se puede mirar en SDSF.
Uso prefix con el nombre del job y luego compruebo el ID, porque puede haber varios PYLISTC en el spool de ejecuciones anteriores.
Leer la salida
browse(row) devuelve todas las líneas de la salida del job: el JES log, el JCL, los mensajes y el SYSPRINT de IDCAMS. El script las escribe tal cual.
Validar el resultado
SDSF muestra el resultado como texto: CC 0000, ABEND S0C4, JCL ERROR... El job ha ido bien si es CC con un número que no pasa de MAX_CC. Lo dejo en 0: solo CC 0000 cuenta como OK. Si para otro job un CC 4 es normal (un aviso, no un error), basta con cambiar esa línea. Un ABEND, un JCL ERROR o un job que no termina a tiempo cuentan siempre como fallo.
El script termina con 0 si el resultado es OK y con 8 si no. Así, quien lance el script sabe si el job ha ido bien sin tener que leer la salida.
Hay otro caso: si el script no llega a enviar el job o a consultarlo (falta TEAMS_WEBHOOK_URL, el prefijo no es válido, falla submit o falla SDSF), o si falla el envío a Teams, termina con 1 y sin aviso en Teams.
El aviso a Teams
Para la tarjeta no hace falta escribir nada nuevo: post_to_teams() es la función de spool_alert.py, de la entrada de pySDSF. Como el proyecto spool-alert está instalado en el entorno virtual de PYBATCH (lo instalamos con su pyproject.toml), spool_alert es un módulo más del entorno, como pySDSF, y se importa con un import.
La URL del webhook tampoco está en el script: la lee de la variable TEAMS_WEBHOOK_URL, que carga el .profile de PYBATCH, como en las entradas anteriores de la categoría “Python” de la web. Si no está, el script termina antes de enviar el job.
La tarjeta lleva en el título el nombre del sistema, el job y el resultado (OK o FAILED), y debajo el LISTCAT que ha hecho y el código de retorno.
Subirlo
Lo subo en binario a /u/pybatch/scripts y, como IBMUSER desde OMVS, le pongo la etiqueta de texto, igual que a los otros scripts:
chtag -tc ISO8859-1 /u/pybatch/scripts/submit_job.py

Probarlo desde OMVS
Primero lo lanzo a mano desde OMVS, como IBMUSER, con el Python del entorno virtual. Por eso, en esta prueba el job enviado lleva el usuario IBMUSER, y el aviso usa el webhook que carga mi .profile:
/u/pybatch/venv/bin/python3 /u/pybatch/scripts/submit_job.py IBMUSERSubmitted PYLISTC(JOB05051) for LISTCAT LEVEL(IBMUSER)
Después aparece la salida completa del job, que acaba con el resultado de IDCAMS y, en la última línea, el resultado del aviso a Teams:
0IDC0001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0
...
0IDC0002I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 0
OK: Teams answered HTTP 202El HTTP 202 es la respuesta del webhook de Teams: ha aceptado la tarjeta.


Además, habrá llegado la notificación del resultado del job a Microsoft Teams.

En OMVS la salida es larga y las primeras líneas se pierden por arriba. Por eso es más cómodo lanzarlo por job: todo lo que escribe el script queda en el STDOUT del job y se puede ver entero en SDSF.
Lanzarlo por job como PYBATCH
Igual que en la entrada del entorno virtual, un job con BPXBATCH y USER=PYBATCH:
//PYSUBMIT JOB (ACCT),'PYBATCH SUBMIT',CLASS=A,MSGCLASS=X,
// NOTIFY=&SYSUID,USER=PYBATCH,REGION=256M
//* Run submit_job.py: build a LISTCAT job, submit it and wait
//* for its result with pySDSF
//RUN EXEC PGM=BPXBATCH
//STDOUT DD SYSOUT=*
//STDERR DD SYSOUT=*
//STDPARM DD *
SH export LIBPATH=/u/python/py313/lib:$LIBPATH;
/u/pybatch/venv/bin/python /u/pybatch/scripts/submit_job.py IBMUSER
/*
En el STDOUT de PYSUBMIT están las líneas del script y, entre ellas, la salida de PYLISTC. Al principio:
Submitted PYLISTC(JOB05054) for LISTCAT LEVEL(IBMUSER)
PYLISTC(JOB05054) ended: CC 0000

En el job que ejecuta el script vemos la salida del job que ha lanzado, pero ese job también está en el spool.

En el JES log de PYLISTC se ve que el job se ejecuta con el usuario PYBATCH: el job que envía el script lleva el usuario de quien lo envía, porque su ficha JOB no lleva USER=.
IRR010I USERID PYBATCH IS ASSIGNED TO THIS JOB.
PYBATCH ha podido enviar el job, esperarlo y leer su salida sin darle ningún permiso más de los que ya tenía.
El aviso en Teams: OK y FAILED
Para ver los dos avisos, un job que lanza el script dos veces: con IBMUSER, que tiene data sets, y con un prefijo que no tiene ninguno, NOEXIST.
//PYSUBMT1 JOB (ACCT),'PYBATCH SUBMIT',CLASS=A,MSGCLASS=X,
// NOTIFY=&SYSUID,USER=PYBATCH,REGION=256M
//* Run submit_job.py twice: an existing prefix (expected OK)
//* and a prefix with no data sets (expected FAILED), each one
//* with its alert in Microsoft Teams
//RUN EXEC PGM=BPXBATCH
//STDOUT DD SYSOUT=*
//STDERR DD SYSOUT=*
//STDPARM DD *
SH export LIBPATH=/u/python/py313/lib:$LIBPATH;
P=/u/pybatch/venv/bin/python;
S=/u/pybatch/scripts/submit_job.py;
$P $S IBMUSER;
$P $S NOEXIST
/*
Las dos ejecuciones van separadas con ; y no con &&: así la segunda se lanza aunque la primera termine con 8.
Ahora tendremos tres jobs: el que ejecuta el script (PYSUBMT1) y los dos PYLISTC que ha lanzado.

Con IBMUSER, PYLISTC termina con CC 0000 y el resultado es OK.

Con NOEXIST no hay nada que listar, IDCAMS termina con CC 4 y, como MAX_CC es 0, el script lo da como fallido:
Submitted PYLISTC(JOB05057) for LISTCAT LEVEL(NOEXIST)
PYLISTC(JOB05057) ended: CC 0004
Y en Teams llegan las dos tarjetas: PYLISTC(JOB05056) OK, con CC 0000, y PYLISTC(JOB05057) FAILED, con CC 0004.

PYSUBMT1 termina con RC=2048:
$HASP395 PYSUBMT1 ENDED - RC=2048Es el 8 con el que terminó el script en la segunda ejecución: BPXBATCH, con STDOUT y STDERR en SYSOUT como aquí, devuelve el código de salida (exit status) del shell multiplicado por 256 (8 × 256 = 2048). Y el RC del paso es el resto de dividir ese valor entre 4096, así que el código de salida tiene que ser 15 o menos: con 16 (16 × 256 = 4096), el paso terminaría con RC=0000. El 8 no tiene ese problema. Con las dos ejecuciones separadas por ;, el RC del paso es el de la última. Con una sola ejecución, como en PYSUBMIT, el paso de BPXBATCH dice si el job enviado ha ido bien: RC=0 si fue OK y RC=2048 si no (y RC=256 si el script termina con 1). Si después hubiera otro paso que solo debe ejecutarse cuando todo va bien, se puede condicionar a ese RC.

Resumen
- El comando
submitde z/OS UNIX envía un fichero con JCL a JES y devuelve el ID del job. - Desde Python, el JCL se construye con una plantilla, se escribe en EBCDIC y se envía con
subprocess. - Con pySDSF,
status_of_jobs()dice cuándo ha terminado el job ybrowse()devuelve su salida. - El script valida el código de retorno del job con
MAX_CC, avisa por Teams con OK o FAILED y termina con 0 o con 8 (o con 1, sin aviso, si no llega a enviar o consultar el job o falla el envío a Teams). - El aviso reutiliza
post_to_teams()despool_alert, que está instalado en el entorno virtual. - El job enviado se ejecuta con el usuario que lo envía, porque su ficha JOB no lleva
USER=. Lanzado desde el job con BPXBATCH, ese usuario es PYBATCH.
Referencias
- submit - Submit a batch job for background processing (z/OS 3.2, UNIX System Services Command Reference).
- Using SDSF with the Python programming language (IBM Docs, z/OS 3.2).
- string.Template (documentación de Python).
- subprocess (documentación de Python).
- APAR OA47398 (IBM Support): el código de retorno de BPXBATCH, multiplicado por 256, y el resto entre 4096.