batchManagerZos クライアント・ユーティリティーの構成

batchManagerZos クライアント・ユーティリティーを使用して、z/OS 上の Liberty で実行しているバッチ・ジョブを管理できます。

このタスクについて

batchManagerZos クライアント・ユーティリティーは、z/OS 用の Liberty で実行しているバッチ・ジョブを管理するための、ネイティブにコンパイルされたバージョンの batchManager コマンド・ライン・ユーティリティーです。これはネイティブ・プログラムであり、JVM は必要ありません。このユーティリティーは batchManagement-1.0 フィーチャーに組み込まれています。

batchManagerZos クライアント・ユーティリティーは、batchManager コマンド・ライン・ユーティリティーがサポートするコマンドおよびオプションのサブセットをサポートします。コマンドおよびオプションのリストを表示するには、$ batchManagerZos help コマンドを使用してください。

batchManagerZos クライアント・ユーティリティーは、最適化されたローカル・アダプターを使用して、ローカル環境で稼働している Liberty サーバーに接続します。batchManagerZos クライアント・ユーティリティーは、リモート・サーバーには接続できません。

セキュリティーに関する考慮事項
batchManagerZos クライアント・ユーティリティーのセキュリティーに関する動作は、Liberty サーバーが SAF レジストリーを使用するかどうかによって異なります。
  • サーバーが SAF ユーザー・レジストリーを使用する場合、batchManagerZos クライアント・ユーティリティー ID が、バッチ要求の要求元の ID (Java Platform, Enterprise Edition RunAs サブジェクト) として設定されます。
  • サーバーが SAF ユーザー・レジストリーを使用しない場合、batchManagerZos クライアント・ユーティリティー ID は無視されます。この場合、特殊サブジェクト EVERYONE が、バッチ要求の要求元の ID として設定されます。
バッチ・ロール・ベースの許可

サーバーで appSecurity が有効にされている場合、要求元の ID を、要求によって必要とされる適切なバッチ・セキュリティー・ロールに割り当てる必要があります。有効なバッチ・セキュリティー・ロールは、batchAdmin、 batchSubmitter、および batchMonitor です。必要とされるロールに ID を割り当てていないと、要求はセキュリティー例外で失敗します。

許可はセキュリティー許可プロバイダーによって管理されます。サーバーが SAF 許可を使用している場合、 SAF 許可プロバイダーは、要求元の ID の許可を、EJBROLE クラスに定義された SAF リソース・プロファイルへのその ID のアクセス権をチェックすることによって判断します。デフォルトでは、以下のリソース・プロファイルがバッチ・ロールと関連付けられます。
    batchAdmin:     BBGZDFLT.com.ibm.ws.batch.batchAdmin
    batchSubmitter: BBGZDFLT.com.ibm.ws.batch.batchSubmitter
    batchMonitor:   BBGZDFLT.com.ibm.ws.batch.batchMonitor
要求元の ID には、対応するバッチ・ロールが認可されるよう、適切なリソース・プロファイルへの READ アクセス権限が付与される必要があります。

次の例は、クライアント ID bob に 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 および jobPropertiesFile
batchManagerZos クライアント・ユーティリティーを使用してバッチ・ジョブをサブミットする際、jobParametersFile および jobPropertiesFile は、コンマで区切った複数のファイルの使用をサポートします。コンマ区切りリストの最初にあるファイルよりも、後ろにあるファイルのほうが優先されます。コンマ区切りリストの正しい使用法を以下の例に示します。
jobParametersFile=filePath1,filePath2,filePath3
jobPropertiesFile=filePath1,filePath2,filePath3
例えば、制御プロパティー・ファイル内で、--jobParametersFile=<filepath1>--jobParametersFile=<filepath1>,<filepath2> に優先します。結果として、パラメーターは --jobParametersFile=<filepath1> となります。
[17.0.0.3 and later]制御プロパティーおよびジョブ・パラメーター
[17.0.0.3 and later]

ジョブ・パラメーターの 1 つのセットを作成するため、本プログラムは空のセットから始めて、さまざまなソースからプロパティーを継続的にロードします。その後、本プログラムはそれらのプロパティーをマージして単一のセットにします。 すべてのソースの読み取りとロードを行った後、本プログラムは単一プロパティー・セットをジョブ・パラメーターとしてジョブ実行依頼に渡します。

このプロパティー・セットは、次の順序でマージすることによって作成されます。同じキーを持つ同じプロパティーがロードされ、複数回設定される場合、前の値は後の値でオーバーライドされます。次のシーケンスでは、前のステップよりも後のステップのほうが優先順位が高くなります。

  1. --jobParametersFile パラメーターがコマンド・ライン・パラメーターとして含まれている場合、昇順の優先順位で以下のアクションが発生します。
    1. ジョブ・パラメーター制御プロパティーがロードされ、マージされます。これらのプロパティーは、制御プロパティー・ファイルの内部で --jobParameter=key=value として構造化されます。
    2. --jobParametersFile パラメーターが指すファイルの内容がロードされ、マージされます。
    3. コマンド・ライン・ジョブ・パラメーターがロードされ、マージされます。
  2. --jobParametersFile パラメーターがコマンド・ライン・パラメーターとして含まれていない場合、昇順の優先順位で以下のアクションが発生します。
    1. --jobParametersFile 制御プロパティーが指すファイルの内容がロードされ、マージされます。この制御プロパティーは、1 つのみの制御プロパティー・ファイル内にあるか、または、プロパティーがオーバーライドされた場合は複数のファイル内にあります。
    2. ジョブ・パラメーター制御プロパティーがロードされ、マージされます。これらのプロパティーは、制御プロパティー・ファイルの内部で --jobParameter=key=value として構造化されます。
    3. コマンド・ライン・ジョブ・パラメーターがロードされ、マージされます。

この構造は、--controlPropertiesFile パラメーターの優先順位がコマンド・ライン引数よりも低いために発生します。--jobParametersFile パラメーターを指定するレベルによって、それらのファイルの優先順位レベルが決まります。

本プログラムはシーケンス中の各ファイルを読み取ってロードするときに、見つかった --jobParametersFile プロパティーと --jobPropertiesFile プロパティーを縮小して 1 つのプロパティーにします。各プロパティーは、他方のプロパティーの別名です。これらの別名の 1 つでオーバーライドされたコマンド・ライン引数または制御プロパティーは、前にオーバーライドされた制御プロパティー・ファイル内にある、これら 2 つのどちらかのインスタンスに優先します。

注: パラメーターは、別個の行でのみコメントを受け入れます。
ジョブ再始動オプション

batchManagerZos クライアント・ユーティリティー・コマンドのオプション restartTokenFile は、ジョブの再始動を容易にするために submit コマンドで使用可能です。このオプションの値は、再始動されるジョブのインスタンス ID が入っているファイルの名前です。batchManagerZos ユーティリティーはこのファイルを読み書きします。ファイルにインスタンス ID が含まれている場合、そのジョブが再始動されます。ファイルにインスタンス ID が含まれていない場合、 新しいジョブがサブミットされ、その結果のインスタンス ID がファイルに保管されます。ジョブが再始動可能な状況で終了しない場合、そのインスタンス ID はファイルから削除されます。このファイルは、データ・セット名 (¥'USER.MY.FILE¥')、ファイル (/u/user/myfile)、または DD (DD:RSTRTID) にすることができます。

注: すべての引用符は円記号 (¥) でエスケープする必要があります。

ジョブ再始動オプションの例を以下に示します。

以下のサンプル・ファイルは、JCL プロシージャーであり、別のライブラリーに保管できます。
//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 
以下のサンプル・ファイルは、サブミットして上記の JCL プロシージャーを実行できる 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
//*
ジョブ・ログのストリーミング

submit コマンドまたは restart コマンドに --getJobLog--queueManagerName、および --wait コマンド・オプションが指定されている場合、 クライアントは、ジョブ・ログ・イベントをサブスクライブし、受け取ったメッセージを STDOUT に出力します。ジョブ・ログ・イベントを受け取るには、 バッチ・ジョブ・イベント公開の有効化が必要です。バッチ・ジョブ・イベント公開の構成について詳しくは、 『バッチ・ジョブ・イベント公開の有効化』文書を参照してください。

[16.0.0.4 and later]ジョブ・ログ・イベントの公開は、新規ジョブ・ログ・パートが作成されるか、ジョブが終了するたびに行われます。新規ジョブ・ログ・パートは、 ジョブ・ログ・ファイルごとの最大ログ・レコード数に達したことに基づいて、または、 ジョブ・ログ・イベント公開の最大間隔秒数に達したことに基づいて作成されます。詳しくは、バッチ・ジョブ・ロギング (batchJobLogging) の文書を参照してください。

戻りコード
batchManagerZos クライアント・ユーティリティーは、以下の戻りコードを出力します。
コード 説明
0 タスクは正常に完了しました。
20 必須引数が指定されませんでした。
21 認識されない引数が指定されました。
22 無効な引数値が指定されました。
255 不明なエラーが発生しました。
注: --wait 引数を指定した場合、ユーティリティーは、待機しているジョブの状況について以下の戻りコードを出力します。
コード 説明
33 ジョブが停止しました。
34 ジョブが正常に完了しませんでした。
35 ジョブが正常に完了しました。
36 ジョブが中止されました。
注: BPXBATCH を実行することによって batchManagerZos を実行する場合、BPXBATCH からの戻りコードは batchManagerZos からの戻りコードと一致しません。BPXBATCH は、batchManagerZos 戻りコードを取得し、それを上位へ 1 バイトだけシフトします。例えば、batchManagerZos の戻りコードが 1 の場合、BPXBATCH の戻りコードは、16 進 0x01 を上位へ 1 バイトだけシフトした 0x100、つまり 256 になります。

BPXBATCH を JCL STEP から呼び出す場合、その STEP の戻りコードは、BPXBATCH の戻りコードを切り捨てて、下位 3 桁の 16 進文字を残したものになります。例えば、batchManagerZos の戻りコードが 35 (16 進で 0x23) の場合、BPXBATCH の戻りコードは 0x2300 です。JCL STEP は、この戻りコードを切り捨てて 0x0300 (つまり 768) にします。

制限

batchManagerZos クライアント・ユーティリティー stop コマンドは、ジョブが実行中であるバッチ executor に送信される必要があります。 マルチサーバー環境での stop コマンドは、batchManagerZos クライアント・ユーティリティーの接続先が、ジョブが実行中であるバッチ executor でなく、指定されたバッチ・ディスパッチャーである場合、 BatchJobNotLocalException で失敗する可能性があります。通常、バッチ・ディスパッチャーは、実行依頼要求を受け取って、それらを下流のバッチ executor に分配します。

手順

  1. server.xml ファイル内で batchManagement-1.0 フィーチャーおよび zosLocalAdapters-1.0 フィーチャーを使用可能にします。
    <featureManager>
    	<feature>batchManagement-1.0</feature>
    	<feature>zosLocalAdapters-1.0</feature>
    </featureManager>
  2. zosLocalAdapters-1.0 エンドポイントを構成します。 次の例は、zosLocalAdapters-1.0 エンドポイント構成を示します。
    <zosLocalAdapters wolaGroup="LIBERTY" wolaName2="BATCH" wolaName3="MANAGER"/>
  3. batchManagerZos クライアント・ユーティリティーが zosLocalAdapters エンドポイントに接続するのを許可します。 batchManagerZos クライアントが、最適化されたローカル・アダプターを介してサーバーに接続するためには、 クライアントの userId に、zosLocalAdapters エンドポイントと関連付けられた CBIND SAF リソースへの許可が付与されている必要があります。エンドポイントと関連付けられたリソースは、 CBIND クラス内で BBG.WOLA.{wolaGroup}.{wolaName2}.{wolaName3} という名前が付けられます。LIBERTY BATCH MANAGER という名前の zosLocalAdapters エンドポイントにバインドするには、 CBIND クラス内のリソース BBG.WOLA.LIBERTY.BATCH.MANAGER への読み取りアクセス権限を batchManagerZos ユーザー ID に付与する必要があります。次の例は、 リソースへの読み取りアクセス権限を付与するために使用する必要のある RACF コマンドを示します。
        RDEFINE CBIND BBG.WOLA.LIBERTY.BATCH.MANAGER UACC(NONE)   
        PERMIT BBG.WOLA.LIBERTY.BATCH.MANAGER CLASS(CBIND) ACCESS(READ) ID(bob)
    注: この例では、batchManagerZos を実行しているユーザーは bob です。
  4. batchManagerZos 要求がクライアントの ID の下でサーバーで実行するようにしたい場合、 SAFCRED z/OS 認可リソースを使用する権限をサーバーに付与する必要があります。 次の例は、SAFCRED z/OS 認可リソースをサーバーが使用できるようにするために使用する必要のある RACF コマンドを示します。
        RDEFINE SERVER BBG.AUTHMOD.BBGZSAFM.SAFCRED UACC(NONE)   
        PERMIT BBG.AUTHMOD.BBGZSAFM.SAFCRED CLASS(SERVER) ACCESS(READ) ID(wlpuser1)
  5. Angel アドレス・スペースを開始します。
  6. Liberty サーバーを開始します。
  7. ping コマンドを使用して、batchManagerZos クライアントと Liberty サーバーの間の接続をテストします。
    $ batchManagerZos ping '--batchManager=LIBERTY BATCH MANAGER'

    ping が成功した場合、クライアントは戻りコード 0 で終了します。ping が成功しなかった場合、エラー・メッセージが発行されます。

  8. トラブルシューティングのために、$ export batchManagerZosTrace=1 環境変数を設定して、クライアントでの追加トレースを有効にすることができます。 バッチ・ジョブの実行に、追加トレースが含まれるようになりました。

    次の例は、REST を使用し、キュー・マネージャーのサブスクリプションを使用せずに実行されるバッチ・ジョブをサブミットするコマンドを示しています。

    $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. オプション: ポーリングを使用した待機ではなく、バッチ・ジョブ・イベントの終了を待機するように、batchManagerZos クライアント・ユーティリティーを構成します。

    WebSphere MQ メッセージング・プロバイダーを使用するジョブ関連イベントの公開が可能になるように、バッチ・サーバーを構成する必要があります。『バッチ・ジョブ・イベント公開の有効化』文書を参照してください。

    [17.0.0.2 and later]ステップ 8 の例を使用すると、以下を追加することで、ジョブをサブミットし、ジョブ終了イベントによるジョブの完了を待機することができます。
    --queueManagerName=[name of MQ queue manager]
    クライアント・サイドから、ローカル・キュー・マネージャーおよび、対応するジョブ・イベントがサーバー構成に基づいてパブリッシュされるトピック・ルートを指すことができます。ローカル・キュー・マネージャーは、 queueManagerName プロパティーによって指定されます。指定される場合、キューのキュー名とトピック・ルートは、以下のプロパティーを使用して、一緒に設定することも、独立して設定することもできます。
    --queueName=[name of MQ managed queue]
    --topicRoot=[name of topic root set for MQ queue]
    queueName プロパティーを使用して WebSphere Application Server for z/OS システムで指定したジョブ・イベントに対するサブスクリプションには、管理対象キューを使用できます。topicRoot プロパティーを使用することで、サーバーが使用する非デフォルトのトピック・ルートを指定することも可能です。
    batchManagerZos クライアントは、ジョブ・インスタンスの終了状態を表す、次の 3 つのイベントの 1 つを受信するまで待機します。
    batch/jobs/execution/stopped 
    batch/jobs/execution/failed 
    batch/jobs/execution/completed
    1. オプション: [17.0.0.1 and later]Liberty 構成で、batchJmsEvents エレメントに topicRoot 属性を追加できます。topicRoot 属性は、バッチ・イベント・トピック・ツリーのルートを変更します。新しいツリーの下のイベントをサブスクライブするには、 wait オプションと一緒に topicRoot パラメーターを組み込みます。
      $ 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]

トピックのタイプを示すアイコン タスク・トピック

ファイル名: twlp_batchManagerZos.html