For z/OS platforms

配置 batchManagerZos 客户机实用程序

可通过使用 batchManagerZos 客户机实用程序管理在 z/OS 上的 Liberty 中运行的批处理作业。

关于此任务

batchManagerZos 客户机实用程序是 batchManager 命令行实用程序的本地编译版本,batchManager 命令行实用程序用于管理在 Liberty for z/OS 上运行的批处理作业。它是一个本地程序,不需要 JVM。该实用程序是 batchManagement-1.0 功能部件随附的。

batchManagerZos 客户机实用程序支持 batchManager 命令行实用程序支持的命令和选项的一部分。请使用 $batchManagerZos help 命令查看命令和选项列表。

batchManagerZos 客户机实用程序使用优化本地适配器连接至本地环境中运行的 Liberty 服务器。batchManagerZos 客户机实用程序无法连接至远程服务器。

安全注意事项
batchManagerZos 客户机实用程序的安全行为取决于 Liberty 服务器是否使用 SAF 注册表。
  • 如果服务器正在使用 SAF 用户注册表,那么 batchManagerZos 客户机实用程序身份设置为批处理请求的请求者的身份(Java 平台企业修订版 RunAs 主体集)。
  • 如果此服务器未在使用 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
必须为请求者的身份授予对相应资源概要文件的读访问权,这样他才能被授予相应的批处理角色。

以下示例说明用于向客户机身份 bob 授予 batchAdmin 角色权限的 RACF 命令。

    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 and later]控制属性和作业参数
[17.0.0.3 and later]

为了构建单个作业参数集合,程序从一个空集合开始,并不断地装入来自各种源的属性。然后,程序将这些属性合并到单个集合中。程序在读取并装入所有源之后,将该单个属性集合作为作业参数传递至作业提交。

该属性集合是按此顺序以合并方式构建的。如果多次装入并设置具有相同键的相同属性,那么后面的值会覆盖先前的值。此序列中后面的步骤具有高于前面的步骤的优先级。

  1. 如果包括 --jobParametersFile 参数作为命令行参数,那么下列操作会按优先级升序顺序发生:
    1. 装入并合并作业参数控制属性。在控制属性文件内,这些属性以 --jobParameter=key=value 形式构造。
    2. 装入并合并 --jobParametersFile 参数所引用的文件的内容。
    3. 装入并合并命令行作业参数。
  2. 如果未包括 --jobParametersFile 参数作为命令行参数,那么下列操作会按优先级升序顺序发生:
    1. 装入并合并 --jobParametersFile 控制属性所引用的文件的内容。此控制属性可能仅出现在一个控制属性文件中,也可能出现在多个文件中(如果此属性被覆盖)。
    2. 装入并合并作业参数控制属性。在控制属性文件内,这些属性以 --jobParameter=key=value 形式构造。
    3. 装入并合并命令行作业参数。

生成这种结构是因为 --controlPropertiesFile 参数具有比命令行自变量低的优先级。您在其中指定 --jobParametersFile 参数的级别决定了这些文件的优先级。

当程序按顺序读取并装入每个文件时,程序将找到的 --jobParametersFile--jobPropertiesFile 属性折叠到单个属性中。每个属性都是另一个属性的别名。具有其中某个别名的命令行自变量或控制属性覆盖项将取代早期被覆盖的控制属性文件中出现的这两种覆盖项中任一项的实例。

注: 参数仅接受单独的行中的注释。
作业重新启动选项

batchManagerZos 客户机实用程序命令选项 restartTokenFile 可在 submit 命令中使用,以方便作业重新启动。此选项的值是用于保存将要重新启动的作业的实例标识的文件名。此文件由 batchManagerZos 实用程序读取和写入。如果此文件包含实例标识,那么会重新启动作业。如果此文件不包含实例标识,那么会提交新作业,并会在文件中存储生成的实例标识。如果作业未以可重新启动状态结束,那么会从此文件移除实例标识。该文件可以是数据集名称 (\'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 and later]无论何时创建新的作业日志部分或者无论何时作业结束,都会发布作业日志事件。将根据达到每个作业日志文件的最大日志记录数或达到作业日志事件的最大发布时间间隔秒数创建新的作业日志部分。有关更多信息,请参阅 的文档。

返回码
batchManagerZos 客户机实用程序输出以下返回码:
代码 描述
0 任务正常完成。
20 未指定必需的自变量。
21 指定了无法识别的自变量。
22 指定了无效自变量值。
255 发生未知错误。
注: 如果您指定 --wait 自变量,那么该实用程序输出以下返回码以指示您正在等待的作业的状态。
代码 描述
33 该作业已停止。
34 该作业未成功完成。
35 该作业已成功完成。
36 该作业已被放弃。
注: 如果通过运行 BPXBATCH 来运行 batchManagerZos,那么 BPXBATCH 的返回码与 batchManagerZos 的返回码不匹配。BPXBATCH 采用 batchManagerZos 返回码,并将其上移一个字节。例如,如果 batchManagerZos 返回 1,那么 BPXBATCH 将返回 256,它是十六进制值 0x01,上移一个字节为 0x100。

如果您从 JCL STEP 调用 BPXBATCH,那么 STEP 返回码被截断为来自 BPXBATCH 的返回码的最后三个十六进制字符。例如,如果 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 端点,您必须对 batchManagerZos userID 授予对类 CBIND 中的资源 BBG.WOLA.LIBERTY.BATCH.MANAGER 的读访问权。以下示例说明授予对该资源的读访问权时必须使用的 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'

    如果 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 客户机将等待接收一个(共三个)表示作业实例已结束状态的事件:
    batch/jobs/execution/stopped 
    batch/jobs/execution/failed 
    batch/jobs/execution/completed
    1. 可选: [17.0.0.1 and later]Liberty 配置中,可以将 topicRoot 属性添加到 batchJmsEvents 元素。 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