適用於 z/OS 平台

配置 batchManagerZos 用戶端公用程式

您可以使用 batchManagerZos 用戶端公用程式,管理正在 z/OS 的 Liberty 上執行的批次工作。

關於這項作業

batchManagerZos 用戶端公用程式是 batchManager 指令行公用程式的原生編譯版本,用來管理正在 z/OS 的 Liberty 上執行的批次工作。它是原生程式,不需要 JVM。此公用程式隨附於 batchManagement-1.0 特性中。

batchManagerZos 用戶端公用程式支援 batchManager 指令行公用程式支援的一部分指令和選項。如果要檢視指令和選項清單,請使用 $batchManagerZos help 指令。

batchManagerZos 用戶端公用程式使用最佳化本端配接器,來連接正在本端環境中執行的 Liberty 伺服器。batchManagerZos 用戶端公用程式無法連接遠端伺服器。

安全考量
batchManagerZos 用戶端公用程式的安全行為,取決於 Liberty 伺服器是否使用 SAF 登錄。
  • 如果伺服器使用 SAF 使用者登錄,會將 batchManagerZos 用戶端公用程式身分設為批次要求的要求端身分(Java Platform Enterprise Edition 執行身分主體)。
  • 如果伺服器沒有使用 SAF 使用者登錄,則會忽略 batchManagerZos 用戶端公用程式身分。在此情況下,會將 EVERYONE 特殊主體設為批次要求的要求端身分。
批次角色型授權

如果在伺服器中啟用了 appSecurity,您必須將要求端身分指派給該要求所需的適當批次安全角色。有效的批次安全角色為 batchAdmin、batchSubmitter 和 batchMonitor。如果未指派身分給所需的角色,該要求會因安全異常狀況而失敗。

授權由安全授權提供者來管理。如果伺服器使用 SAF 授權,SAF 授權提供者會根據 EJBROLE 類別中的定義,檢查該身分對 SAF 資源設定檔的存取權,來判斷要求端身分的授權。依預設,批次角色相關聯的資源設定檔如下。
    batchAdmin:     BBGZDFLT.com.ibm.ws.batch.batchAdmin
    batchSubmitter: BBGZDFLT.com.ibm.ws.batch.batchSubmitter
    batchMonitor:   BBGZDFLT.com.ibm.ws.batch.batchMonitor
要求端身分必須獲授與對適當資源設定檔的 READ 存取權,才能獲得對應批次角色的權限。

下列範例說明 RACF 指令,以授與用戶端身分 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 用戶端公用程式來提交批次工作時,jobParametersFilejobPropertiesFile 支援使用以逗點區隔的多個檔案。在逗點區隔清單中,後面的檔案優先於清單中出現在前面的檔案。 下列範例說明逗點區隔清單的正確用法。
jobParametersFile=filePath1,filePath2,filePath3
jobPropertiesFile=filePath1,filePath2,filePath3
比方說,--jobParametersFile=<filepath1> 會置換控制內容檔中的 --jobParametersFile=<filepath1>,<filepath2>。 產生的參數是 --jobParametersFile=<filepath1>
[17.0.0.3 以及更新版本]控制項內容和工作參數
[17.0.0.3 以及更新版本]

為了建置單一工作參數集,程式一開始會是空集合,且會持續從不同來源載入內容。接著,程式會將內容合併成單一集合。 在程式讀取並載入所有來源之後,程式會將單一內容集當成工作參數傳遞給工作提交。

這個內容集是藉由依此順序合併建置而成的。當具有相同索引鍵的相同內容載入並設定多次時,後續的值會置換先前的值。在此順序中,後續步驟的優先順序高於先前步驟。

  1. 如果以指令行參數形式包含 --jobParametersFile 參數,會依遞增優先順序,進行下列動作:
    1. 載入及合併工作參數控制項內容。這些內容會結構化成控制項內容檔內的 --jobParameter=key=value
    2. 載入及合併 --jobParametersFile 參數所參照之檔案的內容。
    3. 載入及合併指令行工作參數。
  2. 如果未以指令行參數形式包含 --jobParametersFile 參數,會依遞增優先順序,進行下列動作:
    1. 載入及合併 --jobParametersFile 控制項內容所參照之檔案的內容。此控制項內容可能只出現在一個控制項內容檔中,也可能出現在多個檔案中(如果內容被置換的話)。
    2. 載入及合併工作參數控制項內容。這些內容會結構化成控制項內容檔內的 --jobParameter=key=value
    3. 載入及合併指令行工作參數。

會出現此結構是因為 --controlPropertiesFile 參數的優先順序低於指令行引數。您是在哪個層次指定 --jobParametersFile 參數,會決定那些檔案的優先順序層次。

當程式依序讀取及載入每一個檔案時,程式會將找到的 --jobParametersFile--jobPropertiesFile 內容收合成單一內容。每一個內容各是另一內容的別名。使用其中一個別名的指令行引數或控制項內容置換,會取代出現在先前被置換控制項內容檔中的這兩者之一的實例。

註: 參數只接受分隔線上的註解。
工作重新啟動選項

submit 指令上,可以利用 batchManagerZos 用戶端公用程式指令選項 restartTokenFile 來協助重新啟動工作。 這個選項的值是檔案名稱,該檔案保留要重新啟動之工作的實例 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
//*
工作日誌串流

如果在 submitrestart 指令上指定 --getJobLog--queueManagerName--wait 指令選項,用戶端會訂閱工作日誌事件,並將收到的訊息列印至 STDOUT。 為了接收工作日誌事件,必須啟用批次工作事件發佈。如需配置批次工作事件發佈的相關資訊,請參閱啟用批次工作事件發佈的說明文件。

[16.0.0.4 以及更新版本]每當建立新的工作日誌部分,或每當工作已結束時,就會發佈工作日誌事件。建立新的工作日誌部分是根據達到每一工作日誌檔的日誌記錄數上限,或達到發佈工作日誌事件之間的秒數上限。 如需相關資訊,請參閱 的相關說明文件。

回覆碼
batchManagerZos 用戶端公用程式所輸出的回覆碼如下:
代碼 說明
0 作業正常完成。
20 未指定必要引數。
21 指定的引數無法辨識。
22 指定的引數值無效。
255 發生不明錯誤。
註: 如果您指定 --wait 引數,公用程式會輸出下列回覆碼,指出您正在等待之工作的狀態。
代碼 說明
33 工作已停止。
34 工作未順利完成。
35 工作已順利完成。
36 工作已被放棄。
註: 如果您藉由執行 BPXBATCH 來執行 batchManagerZos,BPXBATCH 的回覆碼會與 batchManagerZos 的回覆碼不符。BPXBATCH 會採用 batchManagerZos 回覆碼,且最多進位 1 個位元組。比方說,如果 batchManagerZos 傳回 1,BPXBATCH 傳回 256,(即十六進位值 0x01),則最多進位 1 個位元組變成 0x100。

如果從 JCL STEP 呼叫 BPXBATCH,會截斷 STEP 回覆碼,變成 BPXBATCH 回覆碼的 3 個低位十六進位字元。比方說,如果 batchManagerZos 傳回 35(即十六進位 0x23),BPXBATCH 將傳回 0x2300。JCL STEP 會將回覆碼截斷成 0x0300 或 768。

限制

batchManagerZos 用戶端公用程式的 stop 指令必須引導至執行工作的批次執行程式。在多伺服器環境中,如果 batchManagerZos 用戶端公用程式連接至指定的批次分派器,而不是正在執行工作的批次執行程式,Stop 指令可能因 BatchJobNotLocalException 而失敗。批次分派器通常會收到提交要求,並將這些要求分送到下游的批次執行程式。

程序

  1. server.xml 檔中啟用 batchManagement-1.0zosLocalAdapters-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 userID。下列範例說明當您授與對資源的存取權時,必須使用的 RACF 指令。
        RDEFINE CBIND BBG.WOLA.LIBERTY.BATCH.MANAGER UACC(NONE)   
        PERMIT BBG.WOLA.LIBERTY.BATCH.MANAGER CLASS(CBIND) ACCESS(READ) ID(bob)
    註: 在本例中,bob 是執行 batchManagerZos 的使用者。
  4. 如果您希望以用戶端身分,在伺服器上執行 batchManagerZos 要求,您必須授權伺服器使用 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'

    如果連線測試成功,用戶端會結束,並產生回覆碼 0。如果連線測試失敗,則會發出錯誤訊息。

  8. 如果要進行疑難排解,您可以設定 $ export batchManagerZosTrace=1 環境變數,在用戶端中啟用額外追蹤。 現在執行批次工作會包含額外的追蹤。

    下列範例說明的指令,會提交使用 REST 來執行的批次工作,並且不訂閱佇列管理程式。

    $batchManagerZos submit
    --batchManager=LIBERTY+BATCH+MANAGER  
    --applicationName=[包裝批次應用程式時所用的應用程式名稱]
    --jobXMLName=[應用程式 batch-jobs 目錄中的工作 XML 檔基本名稱]
    --wait
  9. 選擇性的: 將 batchManagerZos 用戶端公用程式配置成等待批次工作事件結束,而不是利用輪詢來等待。

    您必須配置批次伺服器,以便能夠發佈使用 WebSphere MQ 傳訊提供者的工作相關事件。請參閱啟用批次工作事件發佈的相關說明文件。

    [17.0.0.2 以及更新版本]使用步驟 8 中的範例,您可以新增下列字行,提交工作並根據工作結束事件,等待其完成:
    --queueManagerName=[MQ 佇列管理程式的名稱]
    從用戶端,您可以根據伺服器配置,指向本端佇列管理程式以及對應工作事件發佈所在的根主題。本端佇列管理程式是用 queueManagerName 內容來指定。若有指定,可以利用下列內容,來一起或分開設定佇列名稱和佇列根主題:
    --queueName=[MQ 受管理佇列的名稱]
    --topicRoot=[設定給 MQ 佇列的根主題名稱]
    您可以利用 queueName 內容,使用受管理佇列來訂閱您在 WebSphere Application Server for z/OS 系統上指定的工作事件。您可以利用 topicRoot 內容,指定非預設根主題,以供您的伺服器使用。
    下列三個事件是代表工作實例的結束狀態,batchManagerZos 用戶端會等待接收其中一個:
    batch/jobs/execution/stopped 
    batch/jobs/execution/failed 
    batch/jobs/execution/completed
    1. 選擇性的: [17.0.0.1 以及更新版本]Liberty 配置中,可以將 topicRoot 屬性新增至 batchJmsEvents 元素。 topicRoot 屬性會變更批次事件主題樹狀結構的根。如果要訂閱新樹狀結構下的事件,請併入 topicRoot 參數和 wait 選項。
      $ batchManagerZos submit  
      --batchManager=LIBERTY+BATCH+MANAGER  
      --applicationName=[包裝批次應用程式時所用的應用程式名稱]
      --jobXMLName=[應用程式 batch-jobs 目錄中的工作 XML 檔基本名稱]
      --queueManagerName=[MQ 佇列管理程式的名稱]--wait
      --topicRoot=[NEW_ROOT]

指示主題類型的圖示 作業主題

檔名:twlp_batchManagerZos.html