Configuración del programa de utilidad de cliente batchManagerZos

Puede gestionar trabajos por lotes que se ejecutan en Liberty en z/OS utilizando el programa de utilidad de cliente batchManagerZos.

Acerca de esta tarea

El programa de utilidad de cliente batchManagerZos es una versión compilada de forma nativa del programa de utilidad de línea de mandatos batchManager para gestionar trabajos por lotes que se ejecutan en Liberty for z/OS. Se trata de un programa nativo y no requiere una JVM. El programa de utilidad se incluye con la característica batchManagement-1.0.

El programa de utilidad de cliente batchManagerZos da soporte a un subconjunto de los mandatos y opciones que están soportados por el programa de utilidad de línea de mandatos batchManager. Utilice el mandato $ batchManagerZos help para ver la lista de los mandatos y las opciones.

El programa de utilidad de cliente batchManagerZos utiliza adaptadores locales optimizados en un servidor Liberty que se ejecuta en un entorno local. El programa de utilidad de cliente batchManagerZos no puede conectarse a servidores remotos.

Consideraciones sobre la seguridad
El comportamiento de seguridad del programa de utilidad de cliente batchManagerZos depende de si el servidor Liberty utiliza un registro SAF.
  • Si el servidor está utilizando un registro de usuarios de SAF, la identidad del programa de utilidad de cliente batchManagerZos se establece como la identidad del solicitante (Java Platform, Enterprise Edition RunAs Subject) para la solicitud de proceso por lotes.
  • Si el servidor no utiliza un registro de usuarios de SAF, la identidad del programa de utilidad de cliente batchManagerZos se ignora. En este caso, el sujeto especial EVERYONE se establece como la identidad del solicitante para la solicitud de proceso por lotes.
Autorización basada en roles por lotes

Si appSecurity está habilitado en el servidor, debe asignar la identidad del solicitante al rol de seguridad de proceso por lotes apropiados que requiere la solicitud. Los roles de seguridad por lotes válidos son batchAdmin, batchSubmitter y batchMonitor. Si no se asigna la identidad al rol necesario, la solicitud falla con una excepción de seguridad.

La autorización la gestiona el proveedor de autorización de seguridad. Si el servidor utiliza la autorización SAF, el proveedor de autorización SAF determina la autorización de la identidad del solicitante comprobando el acceso de la identidad a perfiles de recurso SAF definidos en la clase EJBROLE. De forma predeterminada, los siguientes perfiles de recursos están asociados con los roles por lotes.
    batchAdmin:     BBGZDFLT.com.ibm.ws.batch.batchAdmin
    batchSubmitter: BBGZDFLT.com.ibm.ws.batch.batchSubmitter
    batchMonitor:   BBGZDFLT.com.ibm.ws.batch.batchMonitor
A la identidad del solicitante se le debe otorgar el acceso READ al perfil de recurso apropiado para que tenga autorización del rol de proceso por lotes correspondientes.

El siguiente ejemplo ilustra los mandatos RACF para otorgar a la identidad del cliente, bob, autorización para el rol batchAdmin.

    RDEFINE EJBROLE BBGZDFLT.com.ibm.ws.batch.batchAdmin UACC(NONE)
    PERMIT BBGZDFLT.com.ibm.ws.batch.batchAdmin CLASS(EJBROLE) ID(bob) ACCESS(READ)
jobParametersFile y jobPropertiesFile
Al enviar un trabajo por lotes utilizando el programa de utilidad de cliente batchManagerZos, jobParametersFile y jobPropertiesFile soportan el uso de varios archivos separados con comas. Los archivos posteriores en la lista separada por comas tienen prioridad sobre los archivos que aparecen primero en la lista. El ejemplo siguiente ilustra el uso correcto de la lista separada por comas.
jobParametersFile=filePath1,filePath2,filePath3
jobPropertiesFile=filePath1,filePath2,filePath3
Como ejemplo, --jobParametersFile=<filepath1> alteraría de forma temporal --jobParametersFile=<filepath1>,<filepath2> en el archivo de propiedades de control. El parámetro resultante es --jobParametersFile=<filepath1>.
[17.0.0.3 and later]Propiedades de control y parámetros de trabajo
[17.0.0.3 and later]

Para crear un conjunto único de parámetros de trabajo, el programa se inicia con un conjunto vacío y carga continuamente propiedades de distintos orígenes. Después, el programa fusiona las propiedades en un solo conjunto. Una vez que el programa lee y carga todos los orígenes, el programa pasa el conjunto único de propiedades a la emisión del trabajo como parámetros de trabajo.

Este conjunto de propiedades se crea fusionando en este orden. Cuando se carga la misma propiedad con la misma clave y se establece más de una vez, el último valor altera temporalmente el valor anterior. Los últimos pasos de esta secuencia tienen una prioridad superior sobre los pasos anteriores.

  1. Si el parámetro --jobParametersFile se incluye como parámetro de línea de mandatos, las acciones siguientes se producen en orden de prioridad ascendente:
    1. Las propiedades de control del parámetro de trabajo se cargan y se fusionan. Estas propiedades se estructuran como --jobParameter=key=value dentro del archivo de propiedades de control.
    2. El contenido de los archivos referenciados por el parámetro --jobParametersFile se carga y fusiona.
    3. Los parámetros de trabajo de línea de mandatos se cargan y fusionan.
  2. Si el parámetro --jobParametersFile no está incluido como un parámetro de línea de mandatos, las acciones siguientes se producen en orden de prioridad ascendente.
    1. El contenido de los archivos referenciados por la propiedad de control --jobParametersFile se cargan y se fusionan. Esta propiedad de control podría aparecer en solo un archivo de propiedad de control, o podría aparecer en más de un archivo, si la propiedad se ha alterado temporalmente.
    2. Las propiedades de control del parámetro de trabajo se cargan y se fusionan. Estas propiedades se estructuran como --jobParameter=key=value dentro del archivo de propiedades de control.
    3. Los parámetros de trabajo de línea de mandatos se cargan y fusionan.

Esta estructura se produce porque el parámetro --controlPropertiesFile tiene menos prioridad que los argumentos de la línea de mandatos. El nivel en el cual especifique el parámetro --jobParametersFile determina el nivel de prioridad de estos archivos.

Cuando el programa lee y carga cada archivo en la secuencia, el programa contrae las propiedades --jobParametersFile y --jobPropertiesFile que se encuentran en un solo repositorio. Cada propiedad es un alias de la otra. La alteración temporal de un argumento de línea de mandatos o propiedades de control con uno de estos alias reemplaza una instancia de cualquiera de los dos que aparece en un archivo de propiedades de control modificadas temporalmente anterior.

Nota: Los parámetros aceptan comentarios solo en líneas separadas.
Opción de reinicio de trabajo

La opción del mandato del programa de utilidad de cliente batchManagerZos restartTokenFile está disponible en el mandato submit para facilitar los reinicios de trabajo. El valor de esta opción es el nombre de un archivo que contiene el ID de instancia del trabajo que se reiniciará. El programa de utilidad batchManagerZos lee y escribe el archivo. Si el archivo contiene un ID de instancia, el trabajo se reinicia. Si el archivo no contiene un ID de instancia, se envía un nuevo trabajo y el ID de instancia resultante se almacena en el archivo. Si el trabajo no finaliza en un estado reiniciable, el ID de instancia se elimina del archivo. El archivo puede ser un nombre de conjunto de datos (\'USER.MY.FILE\'), un archivo (/u/user/myfile), o un DD (DD:RSTRTID).

Nota: Todas las comillas se deben especificar con caracteres de escape de barra inclinada invertida \.

Los ejemplos siguientes ilustran la opción de reinicio del trabajo.

Este archivo de ejemplo es un procedimiento JCL y se puede almacenar en una biblioteca independiente.
//LIBBATCH
PROC UN1='unique1',UN2='unique2'               
//STEP1 EXEC PGM=BPXBATSL                                 
//STDOUT    DD SYSOUT=*                                      
//STDERR    DD SYSOUT=*                                      
//STDPARM DD *                                            
PGM /u/TESTER1/wlp/lib/native/zos/s390x/batchManagerZos   
submit                                                    
--batchManager=LIBERTY+BATCH+MANAGER                      
--controlPropertiesFile=DD:CPROP                          
--jobParametersFile=DD:JPROP                              
--restartTokenfile=DD:WGRSTRT                             
//WGRSTRT DD PATH='/u/TESTER1/restart/&UN1..&UN2..props', 
//            PATHOPTS=(ORDWR,OCREAT),                    
//            PATHMODE=(SIRWXU,SIRWXG)                    
//LIBBATCH PEND 
El archivo de ejemplo es un trabajo JCL que puede enviar que ejecuta el procedimiento JCL.
//ZBATCH JOB (),MSGCLASS=H,CLASS=A,
// USER=TESTER1,PASSWORD=TESTERPW
//MYLIBS1 JCLLIB ORDER=‘TESTER1.PROCS.JCL'
//SUBMIT EXEC PROC=LIBBATCH,UN1='MARY',UN2='D051016'
//CPROP DD *
--applicationName=SimpleBatchJob
--jobXMLName=test_batchlet_stepCtx
--returnExitStatus
--wait
//*
//JPROP DD *
jprop1=value1
//*
Modalidad continua de registro de trabajo

El cliente se suscribe a sucesos de registro de trabajo e imprime los mensajes recibidos en STDOUT, si las opciones de mandato --getJobLog, --queueManagerName y --wait se han especificado en el mandato submit o restart. Para recibir sucesos de registro de trabajo, debe estar habilitada la publicación de sucesos de trabajo por lotes. Si desea más información sobre cómo configurar la publicación de sucesos de trabajo por lotes, consulte la documentación para Habilitación de la publicación de sucesos de trabajo por lotes.

[16.0.0.4 and later]Los sucesos de registro de trabajo se publican siempre que se crea una nueva parte de registro de trabajo o siempre que se finaliza el trabajo. Las nuevas partes de registro de trabajo se crean basándose en si se alcanza el número máximo de registros de trabajo por archivo de registro de trabajo, o bien si se alcanza el número máximo de segundos entre publicaciones de sucesos de registro de trabajo. Si desea más información, consulte la documentación para Registro de trabajo por lotes (batchJobLogging).

Códigos de retorno
El programa de utilidad de cliente batchManagerZos genera los siguientes códigos de retorno:
Código Descripción
0 La tarea se ha completado con normalidad.
20 No se ha especificado un argumento obligatorio.
21 Se ha especificado un argumento no reconocido.
22 Se ha especificado un valor de argumento no válido.
255 Se ha producido un error desconocido.
Nota: Si especifica el argumento --wait, el programa de utilidad genera los siguientes códigos de retorno sobre el estado del trabajo que está esperando.
Código Descripción
33 El trabajo se ha detenido.
34 El trabajo no se ha completado correctamente.
35 El trabajo se ha completado satisfactoriamente.
36 El trabajo se ha abandonado.
Nota: Si ejecuta batchManagerZos ejecutando BPXBATCH, el código de retorno de BPXBATCH no coincide con el código de retorno de batchManagerZos. BPXBATCH toma el código de retorno batchManagerZos y lo desplaza 1 byte hacia arriba. Por ejemplo, si batchManagerZos devuelve 1, BPXBATCH devuelve 256, que es el valor hexadecimal 0x01, desplazado 1 byte a0x100.

Si llamada a BPXBATCH desde un JCL STEP, el código de retorno de STEP se trunca en los 3 caracteres hexadecimales inferiores del código de retorno de BPXBATCH. Por ejemplo, si batchManagerZos devuelve 35, que es 0x23 hex, el BPXBATCH devuelve 0x2300. El JCL STEP trunca el código de retorno a 0x0300 o 768.

Limitaciones

Los mandatos stop del programa de utilidad de cliente batchManagerZos se deben dirigir al ejecutor por lotes donde se está ejecutando el trabajo. Los mandatos stop en un entorno de varios servidores podrían fallar con una BatchJobNotLocalException si el programa de utilidad de cliente batchManagerZos se conecta a un asignador por lotes designado en lugar de al ejecutor por lotes donde se está ejecutando el trabajo. Los asignadores por lotes normalmente reciben solicitudes de envío y las distribuyen a ejecutores por lotes en sentido descendente.

Procedimiento

  1. Habilite las características batchManagement-1.0 y zosLocalAdapters-1.0 en el archivo server.xml.
    <featureManager>
    	<feature>batchManagement-1.0</feature>
    	<feature>zosLocalAdapters-1.0</feature>
    </featureManager>
  2. Configure un punto final zosLocalAdapters-1.0. En el ejemplo siguiente se muestra una configuración de punto final zosLocalAdapters-1.0.
    <zosLocalAdapters wolaGroup="LIBERTY" wolaName2="BATCH" wolaName3="MANAGER"/>
  3. Permita que el programa de utilidad de cliente batchManagerZos se conecte al punto final zosLocalAdapters. Para que el cliente batchManagerZos pueda conectarse al servidor a través de adaptadores locales optimizados, el ID_usuario del cliente debe estar autorizado para el recurso SAF CBIND asociado con el punto final zosLocalAdapters. El recurso que está asociado con el punto final se denomina BBG.WOLA.{wolaGroup}.{wolaName2}.{wolaName3} en la clase CBIND. Para enlazar el punto final zosLocalAdapters denominado LIBERTY BATCH MANAGER, debe otorgar acceso de lectura al recurso BBG.WOLA.LIBERTY.BATCH.MANAGER en la clase CBIND para el ID de usuario de batchManagerZos. En el ejemplo siguiente se muestran los mandatos RACF que debe utilizar para otorgar acceso de lectura al recurso.
        RDEFINE CBIND BBG.WOLA.LIBERTY.BATCH.MANAGER UACC(NONE)   
        PERMIT BBG.WOLA.LIBERTY.BATCH.MANAGER CLASS(CBIND) ACCESS(READ) ID(bob)
    Nota: En este ejemplo, bob es el usuario que ejecuta batchManagerZos.
  4. Si desea que las solicitudes de batchManagerZos se ejecuten en el servidor con la identidad del cliente, debe autorizar al servidor para utilizar los recursos autorizados de SAFCRED z/OS. En el ejemplo siguiente se muestran los mandatos RACF que debe utilizar para habilitar el servidor para que utilice los recursos autorizados de SAFCRED z/OS.
        RDEFINE SERVER BBG.AUTHMOD.BBGZSAFM.SAFCRED UACC(NONE)   
        PERMIT BBG.AUTHMOD.BBGZSAFM.SAFCRED CLASS(SERVER) ACCESS(READ) ID(wlpuser1)
  5. Inicie el espacio de direcciones Angel.
  6. Inicie el servidor Liberty.
  7. Utilice el mandato ping para probar la conectividad entre el cliente batchManagerZos y el servidor Liberty.
    $ batchManagerZos ping '--batchManager=LIBERTY BATCH MANAGER'

    Si el mandato ping es satisfactorio, el cliente sale con un código de retorno 0. Si el mandato ping no es satisfactorio, se emite un mensaje de error.

  8. Para resolver problemas, puede habilitar un rastreo adicional en el cliente estableciendo la variable de entorno $ export batchManagerZosTrace=1. La ejecución de un trabajo por lotes ahora incluye un rastreo adicional.

    El ejemplo siguiente ilustra un mandato que envía un trabajo por lotes que se ejecuta utilizando REST y sin una suscripción al gestor de colas.

    $batchManagerZos submit
    --batchManager=LIBERTY+BATCH+MANAGER
    --applicationName=[nombre de aplicación utilizado al empaquetar la aplicación por lotes]
    --jobXMLName=[nombre base del archivo XML del trabajo en el directorio batch-jobs de la aplicación]
    --wait
  9. Opcional: Configure el programa de utilidad de cliente batchManagerZos para esperar a que salga un suceso de trabajo por lotes, en lugar de esperar utilizando el sondeo.

    Debe configurar el servidor de proceso por lotes para habilitar la publicación de sucesos relacionados con el trabajo que utilizan el proveedor de mensajería WebSphere MQ. Consulte la documentación para Habilitación de la publicación de sucesos de trabajo por lotes.

    [17.0.0.2 and later]Utilizando el ejemplo en el paso 8, puede enviar un trabajo y esperar a que se complete mediante un suceso de finalización de lote añadiendo lo siguiente:
    --queueManagerName=[nombre del gestor de colas MQ]
    Desde el lado del cliente, puede apuntar al gestor de colas local y a la raíz del tema en el que se publican los sucesos de trabajo correspondientes basándose en la configuración del servidor. El gestor de colas local se especifica mediante la propiedad queueManagerName. Si se especifica, el nombre de la cola y la raíz del tema para la cola se puede establecer de forma conjunta o independientemente utilizando las propiedades siguientes:
    --queueName=[nombre de cola gestionada MQ]
    --topicRoot=[nombre de la raíz de tema establecida para la cola MQ]
    Puede utilizar una cola gestionada para la suscripción a los sucesos de trabajo que ha especificado en el sistema WebSphere Application Server para z/OS utilizando la propiedad queueName. Puede especificar una raíz de tema no predeterminada para que utilice el servidor utilizando la propiedad topicRoot.
    El cliente batchManagerZos espera recibir uno de los tres sucesos que representa un estado de finalizado de instancia de trabajo.
    batch/jobs/execution/stopped 
    batch/jobs/execution/failed 
    batch/jobs/execution/completed
    1. Opcional: [17.0.0.1 and later]En la configuración de Liberty, se puede añadir un atributo topicRoot al elemento batchJmsEvents. El atributo topicRoot cambia la raíz del árbol de temas de sucesos por lotes. Para suscribirse a los sucesos bajo el nuevo árbol, incluya el parámetro topicRoot con la opción de espera.
      $ batchManagerZos submit
      --batchManager=LIBERTY+BATCH+MANAGER
      --applicationName=[nombre de aplicación utilizado al empaquetar la aplicación por lotes]
      --jobXMLName=[nombre base del archivo XML del trabajo en el directorio batch-jobs de la aplicación]
      --queueManagerName=[nombre del gestor de colas MQ]
      --wait
      --topicRoot=[NEW_ROOT]

Icono que indica el tipo de tema Tema de tarea

Nombre de archivo: twlp_batchManagerZos.html