NuevoProyecto ETAPEProyecto Emuframe Tape Server (ETAPE)
Python

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 submit
submit is cached /bin/submit

Python en z/OS: enviar jobs desde un script y recibir el resultado en Microsoft Teams – captura 1

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.

Python en z/OS: enviar jobs desde un script y recibir el resultado en Microsoft Teams – captura 2

El script

El script, submit_job.py, hace cinco cosas:

  1. Construye un job a partir de una plantilla: un LISTCAT del prefijo que recibe como argumento (IBMUSER si no recibe ninguno).
  2. Lo envía con submit y se queda con el ID del job.
  3. 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.
  4. Muestra el código de retorno y toda la salida del job.
  5. 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 con chtag -tc IBM-1047.
  • subprocess.run lanza submit con 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 a Jnnnnnnn; la expresión regular acepta las dos formas.
  • El fichero temporal se borra siempre, haya ido bien o no (finally).
  • Si submit falla 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

Python en z/OS: enviar jobs desde un script y recibir el resultado en Microsoft Teams – captura 3

Python en z/OS: enviar jobs desde un script y recibir el resultado en Microsoft Teams – captura 4

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 IBMUSER
Submitted PYLISTC(JOB05051) for LISTCAT LEVEL(IBMUSER)

Python en z/OS: enviar jobs desde un script y recibir el resultado en Microsoft Teams – captura 5

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 202

El HTTP 202 es la respuesta del webhook de Teams: ha aceptado la tarjeta.

Python en z/OS: enviar jobs desde un script y recibir el resultado en Microsoft Teams – captura 6

Python en z/OS: enviar jobs desde un script y recibir el resultado en Microsoft Teams – captura 7

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

Python en z/OS: enviar jobs desde un script y recibir el resultado en Microsoft Teams – captura 8

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
/*

Python en z/OS: enviar jobs desde un script y recibir el resultado en Microsoft Teams – captura 9

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

Python en z/OS: enviar jobs desde un script y recibir el resultado en Microsoft Teams – captura 10

Python en z/OS: enviar jobs desde un script y recibir el resultado en Microsoft Teams – captura 11

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

Python en z/OS: enviar jobs desde un script y recibir el resultado en Microsoft Teams – captura 12

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.

Python en z/OS: enviar jobs desde un script y recibir el resultado en Microsoft Teams – captura 13

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
/*

Python en z/OS: enviar jobs desde un script y recibir el resultado en Microsoft Teams – captura 14

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.

Python en z/OS: enviar jobs desde un script y recibir el resultado en Microsoft Teams – captura 15

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

Python en z/OS: enviar jobs desde un script y recibir el resultado en Microsoft Teams – captura 16

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

Python en z/OS: enviar jobs desde un script y recibir el resultado en Microsoft Teams – captura 17

Y en Teams llegan las dos tarjetas: PYLISTC(JOB05056) OK, con CC 0000, y PYLISTC(JOB05057) FAILED, con CC 0004.

Python en z/OS: enviar jobs desde un script y recibir el resultado en Microsoft Teams – captura 18

PYSUBMT1 termina con RC=2048:

$HASP395 PYSUBMT1 ENDED - RC=2048

Es 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.

Python en z/OS: enviar jobs desde un script y recibir el resultado en Microsoft Teams – captura 19

Resumen

  • El comando submit de 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 y browse() 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() de spool_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

© 2026 Emuframe·🍪 Este sitio solo usa cookies funcionales. Sin rastreo ni recopilación de datos personales.

En esta página