Configuring the batchManagerZos client utility

You can manage batch jobs that are running on Liberty on z/OS by using the batchManagerZos client utility.

About this task

The batchManagerZos client utility is a natively compiled version of the batchManager command-line utility for managing batch jobs that are running on Liberty for z/OS. It is a native program and does not require a JVM. The utility is included with the batchManagement-1.0 feature.

The batchManagerZos client utility supports a subset of the commands and options that are supported by the batchManager command-line utility. Use the $ batchManagerZos help command to view the list of commands and options.

The batchManagerZos client utility uses optimized local adapters to connect to a Liberty server that is running in a local environment. The batchManagerZos client utility cannot connect to remote servers.

Security Considerations
The security behavior of the batchManagerZos client utility depends on whether the Liberty server uses a SAF registry.
  • If the server is using a SAF user registry, then the batchManagerZos client utility identity is set as the requester's identity (the Java Platform, Enterprise Edition RunAs Subject) for the batch request.
  • If the server is not using a SAF user registry, then the batchManagerZos client utility identity is ignored. In this case, the EVERYONE special subject is set as the requester's identity for the batch request.
Batch role-based authorization

If appSecurity is enabled in the server, you must assign the requester's identity to the appropriate batch security role required by the request. Valid batch security roles are batchAdmin, batchSubmitter and batchMonitor. If the identity is not assigned to the role that is required, the request fails with a security exception.

Authorization is managed by the security authorization provider. If the server uses SAF authorization, the SAF authorization provider determines the authorization of the requester's identity by checking the identity's access to SAF resource profiles defined the EJBROLE class. By default, the following resource profiles are associated with the batch roles.
    batchAdmin:     BBGZDFLT.com.ibm.ws.batch.batchAdmin
    batchSubmitter: BBGZDFLT.com.ibm.ws.batch.batchSubmitter
    batchMonitor:   BBGZDFLT.com.ibm.ws.batch.batchMonitor
The requester's identity must be granted READ access to the appropriate resource profile to be authorized to the corresponding batch role.

The following example illustrates the RACF commands to grant the client identity, bob, authorization to the batchAdmin role.

    RDEFINE EJBROLE BBGZDFLT.com.ibm.ws.batch.batchAdmin UACC(NONE)
    PERMIT BBGZDFLT.com.ibm.ws.batch.batchAdmin CLASS(EJBROLE) ID(bob) ACCESS(READ)
jobParametersFile and jobPropertiesFile
When you submit a batch job by using the batchManagerZos client utility, the jobParametersFile and jobPropertiesFilesupports the use of multiple files that are separated by commas. Files later in the comma-separated list take precedence over files that appear first in the list. The following example illustrates correct usage of the comma-separated list.
jobParametersFile=filePath1,filePath2,filePath3
jobPropertiesFile=filePath1,filePath2,filePath3
As an example, --jobParametersFile=<filepath1> would override --jobParametersFile=<filepath1>,<filepath2> in the control properties file. The resulting parameter is --jobParametersFile=<filepath1>.
[17.0.0.3 and later]Control properties and job parameters
[17.0.0.3 and later]

To build a single set of job parameters, the program starts with an empty set and continually loads properties from various sources. The program then merges the properties into a single set. After the program reads and loads all the sources, the program passes the single set of properties to the job submission as the job parameters.

This set of properties is built by merging in this order. When the same property with the same key is loaded and set more than once, the later value overrides the earlier value. The later steps in this sequence have a higher precedence than the earlier steps.

  1. If the --jobParametersFile parameter is included as a command line parameter, the following actions occur in order of ascending precedence:
    1. Job parameter control properties are loaded and merged. These properties are structured as --jobParameter=key=value inside of the control properties file.
    2. The contents of the files that are referenced by the --jobParametersFile parameter are loaded and merged.
    3. Command line job parameters are loaded and merged.
  2. If the --jobParametersFile parameter is not included as a command line parameter, the following actions occur in order of ascending precedence:
    1. The contents of the files that are referenced by the --jobParametersFile control property are loaded and merged. This control property might appear in only one control property file, or it might appear in more than one file if the property was overridden.
    2. Job parameter control properties are loaded and merged. These properties are structured as --jobParameter=key=value inside of the control properties file.
    3. Command line job parameters are loaded and merged.

This structure occurs because the --controlPropertiesFile parameter has less precedence than the command line arguments. The level at which you specify the --jobParametersFile parameter determines the level of precedence of those files.

As the program reads and loads each file in the sequence, the program collapses the --jobParametersFile and --jobPropertiesFile properties that are found into a single property. Each property is an alias of the other. A command line argument or control properties override with one of these aliases supersedes an instance of either of the two that appears in an earlier overridden control properties file.

Note: Parameters accept comments on separate lines only.
Job restart option

The batchManagerZos client utility command option restartTokenFile is available on the submit command to facilitate job restarts. The value of this option is the name of a file that holds the instance ID of the job that is to be restarted. The file is read and written to by the batchManagerZos utility. If the file contains an instance ID, the job is restarted. If the file does not contain an instance ID, a new job is submitted and the resulting instance ID is stored in the file. If the job does not end in a restartable state, the instance ID is removed from the file. The file can be a data set name (\'USER.MY.FILE\'), a file (/u/user/myfile), or a DD (DD:RSTRTID).

Note: All quotations must be escaped with the backslash character \.

The following examples illustrate the job restart option.

This example file is a JCL procedure and can be stored in a separate library.
//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 
The example file is a JCL job that you can submit that executes the JCL procedure.
//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
//*
Job log streaming

The client subscribes to job log events and prints the received messages to the STDOUT if the --getJobLog, --queueManagerName, and --wait command options are specified on the submit or restart command. To receive job log events, batch job events publishing must be enabled. For more information about configuring batch job events publishing, see the documentation for Enabling batch job events publishing.

[16.0.0.4 and later]Job log events are published whenever a new job log part is created or whenever the job has ended. New job log parts are created based on either reaching the maximum number of log records per job log file or reaching the maximum number of seconds between publishes of job log events. For more information, see the documentation for Batch Job Logging (batchJobLogging).

Return codes
The batchManagerZos client utility outputs the following return codes:
Code Description
0 The task completed normally.
20 A required argument was not specified.
21 An unrecognized argument was specified.
22 An invalid argument value was specified.
255 An unknown error occurred.
Note: If you specify the --wait argument, the utility outputs the following return codes about the status of the job that you are waiting for.
Code Description
33 The job stopped.
34 The job did not complete successfully.
35 The job completed successfully.
36 The job was abandoned.
Note: If you run batchManagerZos by running BPXBATCH, the return code from BPXBATCH does not match the return code from batchManagerZos. BPXBATCH takes the batchManagerZos return code and shifts it up by 1 byte. For example, if batchManagerZos returns 1, then BPXBATCH returns 256, which is the hex value 0x01, shifted up 1 byte to 0x100.

If you call BPXBATCH from a JCL STEP, the STEP return code is truncated to the lower 3 hex characters of the return code from BPXBATCH. For example, if batchManagerZos returns 35, which is 0x23 hex, the BPXBATCH returns 0x2300. The JCL STEP truncates the return code to 0x0300, or 768.

Limitations

The batchManagerZos client utility stop commands must be directed at the batch executor where the job is running. Stop commands in a multi-server environment might fail with a BatchJobNotLocalException if the batchManagerZos client utility connects to a designated batch dispatcher rather than the batch executor where the job is running. Batch dispatchers typically receive submission requests and distribute them to downstream batch executors.

Procedure

  1. Enable the batchManagement-1.0 and zosLocalAdapters-1.0 features in your server.xml file.
    <featureManager>
    	<feature>batchManagement-1.0</feature>
    	<feature>zosLocalAdapters-1.0</feature>
    </featureManager>
  2. Configure a zosLocalAdapters-1.0 endpoint. The following example illustrates a zosLocalAdapters-1.0 endpoint configuration.
    <zosLocalAdapters wolaGroup="LIBERTY" wolaName2="BATCH" wolaName3="MANAGER"/>
  3. Permit the batchManagerZos client utility to connect to the zosLocalAdapters endpoint. For the batchManagerZos client to connect to the server over optimized local adapters, the userId of the client must be authorized to the CBIND SAF resource associated with the zosLocalAdapters endpoint. The resource that is associated with the endpoint is named BBG.WOLA.{wolaGroup}.{wolaName2}.{wolaName3} in the CBIND class. To bind the zosLocalAdapters endpoint that is named LIBERTY BATCH MANAGER, you must grant read access to resource BBG.WOLA.LIBERTY.BATCH.MANAGER in class CBIND for the batchManagerZos userID. The following example illustrates the RACF commands that you must use to grant read access to the resource.
        RDEFINE CBIND BBG.WOLA.LIBERTY.BATCH.MANAGER UACC(NONE)   
        PERMIT BBG.WOLA.LIBERTY.BATCH.MANAGER CLASS(CBIND) ACCESS(READ) ID(bob)
    Note: In this example, bob is the user that is running batchManagerZos.
  4. If you want batchManagerZos requests to run on the server under the client's identity, you must authorize the server to use SAFCRED z/OS authorized resources. The following example illustrates the RACF commands that you must use to enable the server to use SAFCRED z/OS authorized resources.
        RDEFINE SERVER BBG.AUTHMOD.BBGZSAFM.SAFCRED UACC(NONE)   
        PERMIT BBG.AUTHMOD.BBGZSAFM.SAFCRED CLASS(SERVER) ACCESS(READ) ID(wlpuser1)
  5. Start the Angel address space.
  6. Start the Liberty server.
  7. Use the ping command to test connectivity between the batchManagerZos client and the Liberty server.
    $ batchManagerZos ping '--batchManager=LIBERTY BATCH MANAGER'

    If the ping was successful, the client exits with a return code of 0. If the ping was not successful, an error message is issued.

  8. To troubleshoot, you can enable extra tracing in the client by setting the $ export batchManagerZosTrace=1 environment variable. Running a batch job now includes extra tracing.

    The following example illustrates a command that submits a batch job that runs by using rest and without a queue manager subscription.

    $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. Optional: Configure the batchManagerZos client utility to wait for a batch job event to exit, instead of waiting by using polling.

    You must configure the batch server to enable the publishing of job-related events that use WebSphere MQ messaging provider. See the documentation for Enabling batch job events publishing.

    [17.0.0.2 and later]Using the example in step 8, you can submit a job and wait for its complete by a job end event by adding the following:
    --queueManagerName=[name of MQ queue manager]
    From the client side, you can point to the local queue manager and the topic root at which the corresponding job events are published based on your server configuration. The local queue manager is specified by queueManagerName property. If specified, the queue name and topic root for the queue can be set together or independently by using the following properties:
    --queueName=[name of MQ managed queue]
    --topicRoot=[name of topic root set for MQ queue]
    You can use a managed queue for the subscription to the job events that you specified on your WebSphere Application Server for z/OS system by using the queueName property. You can specify a non-default topic root for your server to use by using the topicRootproperty.
    The batchManagerZos client waits to receive one of three events that represents a job instance ended state:
    batch/jobs/execution/stopped 
    batch/jobs/execution/failed 
    batch/jobs/execution/completed
    1. Optional: [17.0.0.1 and later]In the Liberty configuration, a topicRoot attribute can be added to the batchJmsEvents element. The topicRoot attribute changes the root of the batch events topic tree. To subscribe to the events under the new tree, include the topicRoot parameter with the wait option.
      $ 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]

Icon that indicates the type of topic Task topic

File name: twlp_batchManagerZos.html