Configuration de l'utilitaire client batchManagerZos

Vous pouvez gérer des travaux par lots qui s'exécutent sous Liberty on z/OS à l'aide de l'utilitaire client batchManagerZos.

Pourquoi et quand exécuter cette tâche

L'utilitaire client batchManagerZos est une version compilée en natif de l'utilitaire de ligne de commande batchManager pour la gestion de travaux par lots qui s'exécutent sous Liberty for z/OS. Il s'agit d'un programme natif et qui ne nécessite pas une machine virtuelle Java. Cet utilitaire est fourni avec la fonction batchManagement-1.0.

L'utilitaire client batchManagerZos prend en charge un sosu-ensemble de commandes et d'options qui sont pris en charge par l'utilitaire de ligne de commande batchManager. Utilisez la commande $ batchManagerZos help pour afficher la liste des commandes et options.

L'utilitaire client batchManagerZos utilise des adaptateurs locaux optimisés pour se connecter à un serveur Liberty qui s'exécute dans un environnement local. L'utilitaire client batchManagerZos ne peut pas se connecter à des serveurs distants.

Remarques sur la sécurité
Le comportement de sécurité de l'utilitaire client batchManagerZos varie selon que le serveur Liberty utilise ou non un registre SAF.
  • Si le serveur utilise un registre d'utilisateur SAF, l'identité de l'utilitaire client batchManagerZos est définie comme l'identité du demandeur (sujet RunAs Java Platform, Enterprise Edition) pour la demande de travail par lots.
  • Si le serveur n'utilise pas de registre d'utilisateurs SAF, l'identité de l'utilitaire client batchManagerZos est ignorée. Dans ce cas, le sujet spécial EVERYONE est défini en tant qu'identité du demandeur pour la demande de travail par lots.
Autorisation par rôle par lots

Si appSecurity est activé dans le serveur, vous devez affecter l'identité du demandeur au rôle de sécurité approprié requis par la demande. Les rôles de sécurité par lots valides sont batchAdmin, batchSubmitter et batchMonitor. Si l'identity n'est pas attribuée au rôle qui est requis, la demande échoue avec une exception de sécurité.

L'autorisation est gérée par le fournisseur d'autorisations de sécurité. Si le serveur utilise l'autorisation SAF, le fournisseur correspondant détermine l'autorisation de l'identité du demandeur en vérifiant l'accès de l'identité aux profils de ressource SAF définis dans la classe EJBROLE. Par défaut, les profils de ressource suivants sont associés aux rôles par lots.
    batchAdmin:     BBGZDFLT.com.ibm.ws.batch.batchAdmin
    batchSubmitter: BBGZDFLT.com.ibm.ws.batch.batchSubmitter
    batchMonitor:   BBGZDFLT.com.ibm.ws.batch.batchMonitor
L'identité du demandeur doit obtenir un accès en lecture au profil de ressource approprié pour être autorisé pour le rôle de traitement par lots correspondant.

L'exemple ci-après illustre les commandes RACF pour accorder à l'identité du client, bob, l'autorisation sur le rôle 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 et jobPropertiesFile
Lorsque vous soumettez un travail par lots à l'aide de l'utilitaire client batchManagerZos, jobParametersFile et jobPropertiesFile prennent en charge l'utilisation de plusieurs fichiers séparés par des virgules. Les fichiers apparaissant en bas de la liste sont prioritaires par rapport aux fichiers qui apparaissent en tête de liste. L'exemple suivant illustre comment utiliser correctement la liste séparée par des virgules.
jobParametersFile=filePath1,filePath2,filePath3
jobPropertiesFile=filePath1,filePath2,filePath3
A titre d'exemple, --jobParametersFile=<filepath1> remplacerait --jobParametersFile=<filepath1>,<filepath2> dans le fichiers de propriétés de contrôle. Le paramètre résultant serait --jobParametersFile=<filepath1>.
[17.0.0.3 and later]Propriétés de contrôle et paramètres de travail
[17.0.0.3 and later]

Pour générer un ensemble unique de paramètres de travail, le programme commence avec un ensemble vide et charge continuellement des propriétés de différentes sources. Le programme fusionne ensuite les propriétés en un ensemble unique. Après avoir lu et chargé toutes les sources, le programme transmet l'ensemble unique de propriétés à la soumission de travaux en tant que paramètres de travail.

Cet ensemble de propriétés est généré en fusionnant dans cet ordre. Lorsque la même propriété avec la même clé est chargée et définie plusieurs fois, la valeur la plus postérieure remplace la valeur antérieure. Les dernières étapes de cette séquence ont une priorité plus élevée que les étapes antérieures.

  1. Si le paramètre --jobParametersFile est inclus en tant que paramètre de ligne de commande, les actions suivantes se produisent par ordre de priorité croissante :
    1. Les propriétés de contrôle des paramètres de travail sont chargées et fusionnées. Ces propriétés sont structurées sous la forme --jobParameter=key=value à l'intérieur du fichier de propriétés de contrôle.
    2. Les contenus des fichiers référencé par le paramètre --jobParametersFile sont chargés et fusionnés.
    3. Les paramètres de travail de la ligne de commande sont chargés et fusionnés.
  2. Si le paramètre --jobParametersFile n'est pas inclus en tant que paramètre de ligne de commande, les actions suivantes se produisent par ordre de priorité croissante :
    1. Les contenus des fichiers référencés par la propriété de contrôle --jobParametersFile sont chargés et fusionnés. Cette propriété de contrôle peut apparaître dans un seul fichier de propriétés de contrôle ou dans plusieurs fichiers si la propriété a été remplacée.
    2. Les propriétés de contrôle des paramètres de travail sont chargées et fusionnées. Ces propriétés sont structurées sous la forme --jobParameter=key=value à l'intérieur du fichier de propriétés de contrôle.
    3. Les paramètres de travail de la ligne de commande sont chargés et fusionnés.

Cette structure se produit car le paramètre --controlPropertiesFile a une priorité inférieure aux arguments de la ligne de commande. Le niveau avec lequel vous spécifiez le paramètre --jobParametersFile détermine le niveau de priorité de ces fichiers.

Alors qu'il lit et charge chaque fichier dans la séquence, le programme réduit les propriétés --jobParametersFile et --jobPropertiesFile trouvées en une seule propriété. Chaque propriété est un alias de l'autre. Le remplacement d'un argument de ligne de commande ou des propriétés de contrôle par l'un de ces alias remplace une instance de l'un des deux apparaissant dans un fichier de propriétés de contrôle remplacé plus tôt.

Remarque : Les paramètres acceptent uniquement les commentaires sur des lignes séparées.
Option de redémarrage de travail

L'option de commande de l'utilitaire client batchManagerZos restartTokenFile est disponible sur la commande submit pour faciliter les redémarrages de travaux. La valeur de cette option est le nom d'un fichier contenant l'ID d'instance du travail à redémarrer. Le fichier est lu et édité par l'utilitaire batchManagerZos. Si le fichier contient un ID d'instance, le travail est redémarré. S'il ne contient pas d'ID d'instance, un nouveau travail est soumis et l'ID d'instance qui en découle est stocké dans le fichier. Si le travail ne se finit pas avec un état redémarrable, l'ID d'instance est supprimé du fichier. Le fichier peut être un nom de fichier (\'USER.MY.FILE\'), un fichier /u/user/myfile) ou une DD (DD:RSTRTID).

Remarque : Tous les guillemets et toutes les apostrophes doivent être échappés avec une barre oblique inversée \.

Les exemples suivants illustrent l'option de redémarrage des travaux.

Ce fichier exemple est une procédure JCL qui peut être stockée dans une bibliothèque à part.
//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 
Ce fichier exemple est un travail JCL que vous pouvez soumettre et qui exécute la procédure 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
//*
Diffusion en flux du journal des travaux

Le client s'abonne aux événements du journal des travaux et imprime les messages reçus dans la sortie standard STDOUT si les options de commande --getJobLog, --queueManagerName et --wait sont spécifiées dans la commande submit ou restart. Pour que les événements du journal des travaux puissent être reçus, il faut que la publication des événements des travaux par lot (Batch) soit activée. Pour plus d'informations sur la configuration de la publication des événements de travail par lots, consultez la documentation pour Activation de la publication d'événements de travail par lots.

[16.0.0.4 and later]Les événements du journal des travaux sont publiés à chaque fois qu'une nouvelle partie du journal des travaux est créée ou à chaque fois que le travail est terminé. La création d'une nouvelle partie du journal des travaux a lieu soit lorsque le nombre maximal d'enregistrements de journal par fichier journal est atteint, soit en cas de dépassement du nombre maximal de secondes entre publications d'événements du journal des travaux. Pour plus d'informations, voir la documentation de Journalisation des travaux par lots (batchJobLogging).

Codes retour
L'utilitaire client batchManagerZos client produit les codes retour suivants :
Code Description
0 La tâche s'est terminée normalement.
20 Un argument obligatoire n'a pas été spécifié.
21 Un argument non reconnu a été spécifié.
22 Un argument non valide a été spécifié.
255 Une erreur inattendue est survenue.
Remarque : Si vous indiquez l'argument --wait, l'utilitaire produit les codes retour suivants concernant l'état du travail que vous attendez.
Code Description
33 Le travail s'est arrêté.
34 Le travail n'a pas abouti.
35 Le travail a abouti.
36 Le travail a été abandonné.
Remarque : Si vous exécutez batchManagerZos en exécutant BPXBATCH, le code de retour de BPXBATCH ne correspond pas au code de retour de batchManagerZos. BPXBATCH prend le code retour de batchManagerZos et l'incrémente d'1 octet. Par exemple, si batchManagerZos renvoie 1, BPXBATCH renvoie 256, qui est la valeur hexadécimale 0x01, augmentée de 1 octet à 0x100.

Si vous appelez BPXBATCH depuis une étape JCL STEP, le code retour de celle-ci est tronquée aux 3 caractères hexadécimaux inférieurs du code retour de BPXBATCH. Par exemple, si batchManagerZos renvoie 35, soit 0x23 hex, BPXBATCH renvoie 0x2300. L'étape JCL STEP tronque le code retour à 0x0300 (ou 768).

Limitations

Les commandes stop de l'utilitaire client batchManagerZos doivent être adressées au programme d'exécution par lots où le travail est exécuté. Les commandes Stop en environnement multi-serveur peuvent échouer avec une exception BatchJobNotLocalException si l'utilitaire client batchManagerZos se connecte à un répartiteur par lots désignés plutôt qu'au programme d'exécution par lots où le travail s'exécute. Les répartiteurs par lots reçoivent généralement des demandes de soumission et les distribuent aux programmes d'exécution par lots en aval.

Procédure

  1. Activez les fonctions batchManagement-1.0 et zosLocalAdapters-1.0 dans votre fichier server.xml.
    <featureManager>
    	<feature>batchManagement-1.0</feature>
    	<feature>zosLocalAdapters-1.0</feature>
    </featureManager>
  2. Configurez un noeud final zosLocalAdapters-1.0. L'exemple ci-après illustre une configuration de noeud final zosLocalAdapters-1.0.
    <zosLocalAdapters wolaGroup="LIBERTY" wolaName2="BATCH" wolaName3="MANAGER"/>
  3. Autorisez l'utilitaire client batchManagerZos à se connecter au noeud final zosLocalAdapters. Pour que le client batchManagerZos se connecte au serveur sur des adaptateurs locaux optimisés, l'élément userId du client doit être autorisé sur la ressource CBIND SAF associée au noeud final zosLocalAdapters. La ressource qui est associée au noeud final se nomme BBG.WOLA.{wolaGroup}.{wolaName2}.{wolaName3} dans la classe CBIND. Pour lier le noeud final zosLocalAdapters nommé LIBERTY BATCH MANAGER, vous devez accorder l'accès en lecture à la ressource BBG.WOLA.LIBERTY.BATCH.MANAGER dans la classe CBIND pour l'ID utilisateur batchManagerZos. L'exemple ci-après illustre les commandes RACF que vous devez utiliser pour accorder un accès en lecture à la ressource.
        RDEFINE CBIND BBG.WOLA.LIBERTY.BATCH.MANAGER UACC(NONE)   
        PERMIT BBG.WOLA.LIBERTY.BATCH.MANAGER CLASS(CBIND) ACCESS(READ) ID(bob)
    Remarque : Dans cet exemple, bob est l'utilisateur qui exécute batchManagerZos.
  4. Si vous voulez que les demandes batchManagerZos s'exécutent sur le serveur sous l'identité du client, vous devez autoriser le serveur à utiliser les ressources autorisées SAFCRED z/OS. L'exemple ci-après illustre les commandes RACF que vous devez utiliser pour permettre au serveur d'utiliser les ressources autorisées SAFCRED z/OS.
        RDEFINE SERVER BBG.AUTHMOD.BBGZSAFM.SAFCRED UACC(NONE)   
        PERMIT BBG.AUTHMOD.BBGZSAFM.SAFCRED CLASS(SERVER) ACCESS(READ) ID(wlpuser1)
  5. Démarrez l'espace adresse Angel.
  6. Démarrez le serveur Liberty.
  7. Utilisez la commande ping pour tester la connectivité entre le client batchManagerZos et le serveur Liberty.
    $ batchManagerZos ping '--batchManager=LIBERTY BATCH MANAGER'

    Si la commande ping aboutit, le client sort avec le code retour 0. Dans le cas contraire, un message d'erreur est émis.

  8. Pour remédier à cela, vous pouvez activer un traçage supplémentaire dans le client en définissant la variable d'environnement $ export batchManagerZosTrace=1. L'exécution d'un travail par lots inclut maintenant le traçage supplémentaire.

    L'exemple suivant illustre une commande soumettant un travail par lots s'exécutant avec REST et sans souscription au gestionnaire de file d'attente.

    $batchManagerZos submit
    --batchManager=LIBERTY+BATCH+MANAGER
    --applicationName=[application name used when packaging the batch app]
    --jobXMLName=[job XML file basename in the app's batch-jobs dir]
    --wait
  9. Facultatif : Configurez l'utilitaire du client batchManagerZos afin d'attendre qu'un événement de travail par lots existe au lieu d'attendre à l'aide d'interrogations.

    Vous devez configurer le serveur de traitement par lots pour permettre la publication des événements associés à un travail utilisant le fournisseur de messagerie WebSphere MQ. Voir la documentation de Activation de la publication d'événements de travail par lots.

    [17.0.0.2 and later]A l'aide de l'exemple fourni à l'étape 8, vous pouvez soumettre un travail et attendre qu'il soit terminé par un événement de fin de travail en ajoutant ce qui suit :
    --queueManagerName=[name of MQ queue manager]
    Du côté du client, vous pouvez désigner le gestionnaire de file d'attente local et la racine de rubrique sur laquelle les événements de travail correspondants sont publiés suivant la configuration de votre serveur. Le gestionnaire de file d'attente local est spécifié par la propriété queueManagerName. Si vous les spécifiez, le nom et la racine de rubrique de la file d'attente peuvent être définies ensemble ou séparément à l'aide des propriétés suivantes :
    --queueName=[name of MQ managed queue]
    --topicRoot=[name of topic root set for MQ queue]
    Vous pouvez utiliser une file d'attente gérée pour l'abonnement aux événements de travaux spécifiés sur votre système WebSphere Application Server for z/OS à l'aide de la propriété queueName. Vous pouvez spécifier une racine de rubrique autre que celle définie par défaut pour le serveur à utiliser à l'aide de la propriété topicRoot.
    Le client batchManagerZos attend de recevoir l'un des trois événements représentant un état de fin d'instance de travail :
    batch/jobs/execution/stopped 
    batch/jobs/execution/failed 
    batch/jobs/execution/completed
    1. Facultatif : [17.0.0.1 and later]Dans la configuration de Liberty, un attribut topicRoot peut être ajouté à l'élément batchJmsEvents. Il permet de changer la racine de l'arborescence de rubriques (topics) d'événements Batch. Pour configurez l'abonnement aux événements sous la nouvelle arborescence, incluez le paramètre topicRoot avec l'option wait.
      $ batchManagerZos submit
      --batchManager=LIBERTY+BATCH+MANAGER
      --applicationName=[application name used when packaging the batch app]
      --jobXMLName=[job XML file basename in the app's batch-jobs dir]
      --queueManagerName=[name of MQ queue manager]
      --wait
      --topicRoot=[NEW_ROOT]

Icône indiquant le type de rubrique Rubrique Tâche

Nom du fichier : twlp_batchManagerZos.html