Für z/OS-Plattformen

Clientdienstprogramm "batchManagerZos" konfigurieren

Sie können Stapeljobs, die in Liberty unter z/OS ausgeführt werden, mit dem Clientdienstprogramm "batchManagerZos" verwalten.

Informationen zu diesem Vorgang

Das Clientdienstprogramm ist eine nativ kompilierte Version des Befehlszeilendienstprogramms "batchManager" zur Verwaltung von Stapeljobs, die in Liberty for z/OS ausgeführt werden. Es ist ein natives Programm und benötigt keine JVM. Das Dienstprogramm wird mit dem Feature batchManagement-1.0 bereitgestellt.

Das Clientdienstprogramm "batchManagerZos" unterstützt eine Untermenge der vom Befehlszeilendienstprogramm "batchManager" unterstützten Befehle und Optionen. Verwenden Sie den Befehl $ batchManagerZos help, um die Liste der Befehle und Optionen anzuzeigen.

Das Clientdienstprogramm "batchManagerZos" verwendet optimierte lokale Adapter, um eine Verbindung mit einem Liberty-Server herzustellen, der in einer lokalen Umgebung ausgeführt wird. Das Clientdienstprogramm "batchManagerZos" kann keine Verbindung zu fernen Servern herstellen.

Sicherheitsaspekte
Das Sicherheitsverhalten des Clientdienstprogramms "batchManagerZos" ist davon abhängig, ob der Liberty-Server eine SAF-Registry verwendet.
  • Wenn der Server eine SAF-Benutzerregistry verwendet, wird die Identität des Clientdienstprogramms "batchManagerZos" als Identität des Requesters (Java Platform, Enterprise Edition-RunAs-Subjekt) für die Stapelanforderung gesetzt.
  • Wenn der Server keine SAF-Benutzerregistry verwendet, wird die ID des Clientdienstprogramms "batchManagerZos" ignoriert. In diesem Fall wird die Sondersubjekt EVERYONE als die Identität des Requesters für die Stapelverarbeitung Anforderung festgelegt.
Stapelrollenbasierte Berechtigung

Wenn appSecurity auf dem Server aktiviert ist, müssen Sie die Identität des Requesters die entsprechende Charge Sicherheitsrolle von der Anforderung erforderlich zuordnen.Gültige Stapelsicherheitsrollen sind batchAdmin, batchSubmitter und batchMonitor. Wird der Identität nicht die erforderlichen Rolle zugewiesen, scheitert die Anforderung mit einer Sicherheitsausnahmebedingung.

Die Berechtigung wird vom Sicherheitsberechtigungsprovider verwaltet. Wenn der Server die SAF-Berechtigung verwendet, bestimmt der SAF-Berechtigungsprovider die Berechtigung der Identität des Requesters, indem er den Zugriff der Identität auf die von der Klasse EJBROLE definierten SAF-Ressourcenprofile überprüft. Standardmäßig sind den Stapelrollen folgende Ressourcenprofile zugeordnet.
    batchAdmin:     BBGZDFLT.com.ibm.ws.batch.batchAdmin
    batchSubmitter: BBGZDFLT.com.ibm.ws.batch.batchSubmitter
    batchMonitor:   BBGZDFLT.com.ibm.ws.batch.batchMonitor
Der Identität des Requesters muss Lesezugriff (READ) auf das entsprechende Ressourcenprofil erteilt werden, damit sie für die zugehörige Stapelrolle berechtigt wird.

Das folgende Beispiel zeigt die RACF-Befehle, mit denen der Clientidentität bob die Berechtigung für die Rolle batchAdmin erteilt wird.

    RDEFINE EJBROLE BBGZDFLT.com.ibm.ws.batch.batchAdmin UACC(NONE)
    PERMIT BBGZDFLT.com.ibm.ws.batch.batchAdmin CLASS(EJBROLE) ID(bob) ACCESS(READ)
jobParametersFile und jobPropertiesFile
Wenn Sie einen Stapeljob mit dem Clientdienstprogramm "batchManagerZos" übergeben, unterstützen jobParametersFile und jobPropertiesFile die Verwendung mehrerer Dateien, die durch Kommas voneinander getrennt angegeben werden müssen. Dateien, die in der durch Kommas getrennte Liste weiter unten stehen, haben Vorrang vor Dateien, die in der Liste zuerst erscheinen. Das folgende Beispiel veranschaulicht die korrekte Verwendung der durch Kommas getrennten Liste.
jobParametersFile=Dateipfad1,Dateipfad2,Dateipfad3
jobPropertiesFile=Dateipfad1,Dateipfad2,Dateipfad3
--jobParametersFile=<Dateipfad1> überschreibt beispielsweise --jobParametersFile=<Dateipfad1>,<Dateipfad2> in der Steuerungseigenschaftendatei. Der generierte Parameter ist --jobParametersFile=<Dateipfad1>.
[17.0.0.3 und höher]Steuerungseigenschaften und Jobparameter
[17.0.0.3 und höher]

Zum Erstellen einer Einzelgruppe von Jobparametern beginnt das Programm mit einer leeren Gruppe und lädt dann fortlaufend Eigenschaften aus unterschiedlichen Quellen. Das Programm führt anschließend die Eigenschaften in einem einzigen Satz zusammen. Nachdem das Programm alle Quellen gelesen und geladen hat, übergibt das Programm den Einzelsatz aus Eigenschaften als Jobparameter an die Jobübergabe.

Dieser Satz aus Eigenschaften wird durch Zusammenführung in dieser Reihenfolge erstellt. Wenn dieselbe Eigenschaft mit demselben Schlüssel geladen und mehr als einmal festgelegt wird, überschreibt der spätere Wert den früheren Wert. Die späteren Schritte in dieser Reihenfolge haben Vorrang vor den früheren Schritten.

  1. Wenn der Parameter --jobParametersFile als Befehlszeilenparameter enthalten ist, treten die folgenden Aktionen in aufsteigender Reihenfolge auf:
    1. Die Jobparameter für die Steuerungseigenschaften werden geladen und zusammengeführt. Diese Eigenschaften sind in der Steuerungseigenschaftendatei wie folgt strukturiert: --jobParameter=key=value.
    2. Die Inhalte der Dateien, die über den Parameter --jobParametersFile referenziert werden, werden geladen und zusammengeführt.
    3. Die Jobparameter für die Befehlszeile werden geladen und zusammengeführt.
  2. Wenn der Parameter --jobParametersFile nicht als Befehlszeilenparameter enthalten ist, treten die folgenden Aktionen in aufsteigender Reihenfolge auf:
    1. Die Inhalte der Dateien, die über die Steuerungseigenschaft --jobParametersFile referenziert werden, werden geladen und zusammengeführt. Diese Steuerungseigenschaft wird möglicherweise nur in einer einzigen Steuerungseigenschaftendatei angezeigt oder sie wird möglicherweise in mehr als einer Datei angezeigt, wenn die Eigenschaft überschrieben wurde.
    2. Die Jobparameter für die Steuerungseigenschaften werden geladen und zusammengeführt. Diese Eigenschaften sind in der Steuerungseigenschaftendatei wie folgt strukturiert: --jobParameter=key=value.
    3. Die Jobparameter für die Befehlszeile werden geladen und zusammengeführt.

Diese Struktur tritt auf, weil der --controlPropertiesFile-Parameter in der Rangfolge den Befehlszeilenargumenten untergeordnet ist. Die Ebene, auf der Sie den --jobParametersFile-Parameter angeben, bestimmt die Rangfolgenebene dieser Dateien.

Während das Programm jede Datei in der Reihenfolge liest und lädt, fasst das Programm die gefundenen Eigenschaften --jobParametersFile und --jobPropertiesFile in einer einzigen Eigenschaft zusammen. Jede Eigenschaft ist ein Alias der anderen. Eine Überschreibung mit einem Befehlszeilenargument oder eine Steuerungseigenschaft mit einem dieser Aliase ersetzt eine Instanz dieser beiden, wenn sie in einer früheren überschriebenen Steuerungseigenschaftendatei enthalten sind.

Anmerkung: Parameter akzeptieren Kommentare nur in separaten Zeilen.
Option für den Jobneustart

Die Befehlsoption restartTokenFile für den Befehl submit im Clientdienstprogramm "batchManagerZos" vereinfacht den Neustart von Jobs. Der Wert dieser Option ist der Namen einer Datei, die die Instanz-ID des Jobs enthält, der neu gestartet werden soll. Die Datei wird vom Dienstprogramm "batchManagerZos" gelesen und beschrieben. Wenn die Datei eine Instanz-ID enthält, wird der Job neu gestartet. Wenn die Datei keine Instanz-ID enthält, wird ein neuer Job übergeben und die generierte Instanz-ID wird in der Datei gespeichert. Wenn der Job am Ende keinen wiederanlauffähigen Status annimmt, wird die Instanz-ID aus der Datei entfernt. Die Datei kann ein Datasetname (\'USER.MY.FILE\'), eine Datei (/u/user/myfile) oder DD (DD:RSTRTID) sein.

Anmerkung: Alle Anführungszeichen müssen mit dem Backslash-Zeichen (\) als Escapezeichen versehen werden.

Die folgenden Beispiele veranschauchlichen die Option für den Jobneustart.

Diese Beispieldatei ist eine JCL-Prozedur und kann in einer separaten Bibliothek gespeichert werden.
//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 
Die Beispieldatei ist ein JCL-Job, den Sie übergeben können, der die JCL-Prozedur ausführt.
//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
//*
Jobprotokollstreaming

Der Client subskribiert Jobprotokollereignisse und druckt die empfangene Nachricht in die Standardausgabe STDOUT, wenn die Befehlsoptionen --getJobLog, --queueManagerName und --wait mit dem Befehl submit oder restart angegeben werden. Wenn Sie Jobprotokollereignisse empfangen möchten, muss die Ereignisveröffentlichung von Stapeljobs aktiviert sein. Weitere Informationen zur Konfiguration der Ereignisveröffentlichung von Stapeljobs finden Sie in der Dokumentation zu Veröffentlichung von Stapeljobereignissen ermöglichen.

[16.0.0.4 und höher]Jobprotokollereignisse werden veröffentlicht, wenn ein neuer Jobprotokollabschnitt erstellt wird oder wenn ein Job beendet wird. Neue Jobprotokollabschnitte werden entweder erstellt, weil die maximale Anzahl von Protokolldatensätzen pro Jobprotokolldatei oder die maximale Anzahl von Sekunden zwischen den Veröffentlichungen von Jobprotokollereignissen erreicht wurde. Weitere Informationen finden Sie in der Dokumentation zur .

Rückgabecodes
Das Clientdienstprogramm "batchManagerZos" gibt die folgenden Rückgabecodes zurück:
Code Beschreibung
0 Die Task wurde normal beendet.
20 Ein erforderliches Argument wurde nicht angegeben.
21 Es wurde ein nicht erkanntes Argument angegeben.
22 Es wurde ein ungültiges Argument angegeben.
255 Es ist ein unbekannter Fehler aufgetreten.
Anmerkung: Wenn Sie das Argument --wait angeben, gibt das Dienstprogramm die folgenden Rückkehrcodes zum Status des Jobs aus, auf den Sie warten.
Code Beschreibung
33 Der Job wurde gestoppt.
34 Der Job wurde nicht erfolgreich ausgeführt.
35 Der Job wurde erfolgreich ausgeführt.
36 Der Job wurde abgebrochen.
Anmerkung: Wenn Sie "batchManagerZos" mit BPXBATCH ausführen, stimmt der von BPXBATCH zurückgegebene Rückgabecode nicht mit dem Rückgabecode von "batchManagerZos" überein. BPXBATCH verschiebt den von "batchManagerZos" zurückgegebenen Rückgabecode um ein Byte nach oben. Wenn "batchManagerZos" z. B. 1 zurückgibt, gibt BPXBATCH 256 zurück. Dies entspricht dem Hexadezimalwert 0x01, um ein Byte nach oben auf 0x100 verschoben.

Wenn Sie BPXBATCH aus einem JCL STEP aufrufen, wird der Rückgabecode auf die drei unteren Hexadezimalzeichen des von BPXBATCH zurückgegbenen Rückgabecodes abgeschnitten. Wenn "batchManagerZos" beispielsweise 35 zurückgibt, was dem Hexadezimalwert 0x23 entspricht, gibt BPXBATCH 0x2300 zurück. Der JCL STEP schneidet den Rückgabecode auf 0x0300, d. h. 768, ab.

Einschränkungen

Die stop-Befehle des Clientdienstprogramms "batchManagerZos" müssen an das Stapelsteuerprogramm, in dem der Job ausgeführt wird, übertragen werden. Stop-Befehle in einer Mehrserverumgebung können mit einer Ausnahme des Typs BatchJobNotLocalException fehlschlagen, wenn das Clientdienstprogramm "batchManagerZos" eine Verbindung zu einem designierten Stapeldispatcher und nicht zu dem Stapelsteuerprogramm herstellt, in dem der Job ausgeführt wird. Stapeldispatchers empfangen gewöhnlich Übergabeanforderungen und verteilen sie an die nachgeordneten Stapelausführungsprogramme.

Vorgehensweise

  1. Aktivieren Sie die Features batchManagement-1.0 und zosLocalAdapters-1.0 in Ihrer Datei server.xml.
    <featureManager>
    	<feature>batchManagement-1.0</feature>
    	<feature>zosLocalAdapters-1.0</feature>
    </featureManager>
  2. Konfigurieren Sie den Endpunkt für zosLocalAdapters-1.0. Im folgenden Beispiel sehen Sie die Endpunktkonfiguration für zosLocalAdapters-1.0.
    <zosLocalAdapters wolaGroup="LIBERTY" wolaName2="BATCH" wolaName3="MANAGER"/>
  3. Ermöglichen Sie dem Clientdienstprogramm "batchManagerZos", eine Verbindung mit dem zosLocalAdapters-Endpunkt herzustellen. Damit der Client "batchManagerZos" über optimierte lokale Adapter eine Verbindung zum Server herstellen kann, muss die Benutzer-ID (userId) des Clients für die CBIND-SAF-Ressource des Endpunkts zosLocalAdapters berechtigt sein. Diese dem Endpunkt zugeordnete Ressource hat den Namen BBG.WOLA.{wolaGroup}.{wolaName2}.{wolaName3} in der Klasse CBIND. Zum Binden des zosLocalAdapters-Endpunkts mit dem Namen LIBERTY BATCH MANAGER benötigt die Ressource BBG.WOLA.LIBERTY.BATCH.MANAGER in der Klasse CBIND für die batchManagerZos-Benutzer-ID Lesezugriff (READ). Das folgende Beispiel zeigt die RACF-Befehle, mit denen der Ressource der Lesezugriff erteilt wird.
        RDEFINE CBIND BBG.WOLA.LIBERTY.BATCH.MANAGER UACC(NONE)   
        PERMIT BBG.WOLA.LIBERTY.BATCH.MANAGER CLASS(CBIND) ACCESS(READ) ID(bob)
    Anmerkung: In diesem Beispiel ist bob der Benutzer, der "batchManagerZos" ausführt.
  4. Wenn batchManagerZos-Anforderungen auf dem Server unter der Clientidentität ausgeführt werden sollen, müssen Sie den Server dazu autorisieren, die berechtigten SAFCRED-z/OS-Ressourcen zu verwenden. Im folgenden Beispiel sind die RACF-Befehle aufgeführt, die es dem Server ermöglichen, die berechtigten SAFCRED-z/OS-Ressourcen zu verwenden.
        RDEFINE SERVER BBG.AUTHMOD.BBGZSAFM.SAFCRED UACC(NONE)   
        PERMIT BBG.AUTHMOD.BBGZSAFM.SAFCRED CLASS(SERVER) ACCESS(READ) ID(wlpuser1)
  5. Starten Sie den Angel-Adressraum.
  6. Starten Sie den Liberty-Server.
  7. Führen Sie den Befehl ping aus, um die Konnektivität zwischen dem batchManagerZos-Client und dem Liberty-Server zu testen.
    $ batchManagerZos ping '--batchManager=LIBERTY BATCH MANAGER'

    Wenn der Pingbefehl erfolgreich war, wird der Client mit dem Rückgabecode 0 beendet. Andernfalls wird eine Fehlernachricht ausgegeben.

  8. Zur Fehlerbehebung können Sie zusätzliches Tracing im Client einstellen, indem Sie die Umgebungsvariable $ export batchManagerZosTrace=1 festlegen. Bei der Ausführung eines Stapeljobs wird jetzt eine zusätzliche Traceerstellung durchgeführt.

    Das folgende Beispiel zeigt einen Befehl, der einen Stapeljob übergibt, der mit REST und ohne Warteschlangenmanagersubskription ausgeführt wird.

    $batchManagerZos submit
    --batchManager=LIBERTY+BATCH+MANAGER  
    --applicationName=[Anwendungsname, der beim Packen der Stapelanwendung verwendet wird]
    --jobXMLName=[XML-Basisdateiname des Jobs im Anwendungsverzeichnis für Stapeljobs]
    --wait
  9. Optional: Konfigurieren Sie das Clientdienstprogramm "batchManagerZos" so, dass es wartet, bis es eine Benachrichtigung über den Abschluss eines Stapeljobereignisses empfängt, anstatt während der Wartezeit fortlaufend Abfragen zu senden.

    Sie müssen den Stapelserver so konfigurieren, dass die Veröffentlichung jobbezogener Ereignisse, die den WebSphere MQ-Messaging-Provider verwenden, ermöglicht wird. Weitere Informationen finden Sie unter Veröffentlichung von Stapeljobereignissen ermöglichen.

    [17.0.0.2 und höher]Wie im Beispiel in Schritt 8 gezeigt, können Sie einen Job übergeben und auf das Jobendereignis warten, indem Sie Folgendes hinzufügen:
    --queueManagerName=[Name des MQ-Warteschlangenmanagers]
    Auf der Clientseite können Sie auf den lokalen Warteschlangenmanager und das Topicstammverzeichnis verweisen, in dem die entsprechenden Jobereignisse je nach Serverkonfiguration veröffentlicht werden. Der lokale Warteschlangenmanager wird mit der Eigenschaft queueManagerName angegeben. Wenn Sie diese Eigenschaft angeben, können Sie den Warteschlangennamen und das Topicstanmmverzeichis für die Warteschlange mit den folgenden Eigenschaften zusammen und unabhängig voneinander festlegen:
    --queueName=[Name der von MQ verwalteten Warteschlange]
    --topicRoot=[Name des für die MQ-Warteschlange festgelegten Topicstammverzeichnisses]
    Sie können eine verwaltete Warteschlange für die Subskription der Jobereignisse, die Sie in Ihrem WebSphere Application Server for z/OS-System festgelegt haben, mit der Eigenschaft queueName angeben. Mit der Eigenschaft topicRoot können Sie ein vom Standard abweichendes Topicstammverzeichnis für Ihren Server angeben.
    Der batchManagerZos-Client wartet auf den Empfang eines von drei Ereignissen, das den Endestatus einer Jobinstanz darstellt:
    batch/jobs/execution/stopped 
    batch/jobs/execution/failed 
    batch/jobs/execution/completed
    1. Optional: [17.0.0.1 und höher]In der Liberty-Konfiguration kann ein topicRoot-Attribut dem Element batchJmsEvents hinzugefügt werden. Das Attribut topicRoot ändert das Stammverzeichnis der Topicstruktur des Stapelereignisses. Wenn Sie die Ereignisse unter der neuen Baumstruktur subskribieren möchten, schließen Sie den Parameter topicRoot in der Option für Warten ein.
      $ batchManagerZos submit  
      --batchManager=LIBERTY+BATCH+MANAGER  
      --applicationName=[Anwendungsname, der beim Packen der Stapelanwendung verwendet wird]
      --jobXMLName=[XML-Basisdateiname des Jobs im Anwendungsverzeichnis für Stapeljobs]
      --queueManagerName=[Name des MQ-Warteschlangenmanagers]--wait
      --topicRoot=[Neues_Stammverzeichnis]

Symbol das den Typ des Artikels anzeigt. Taskartikel

Dateiname: twlp_batchManagerZos.html