Configure the batchManagerZos client utility

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

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 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, we 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 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>.

Control properties and job parameters

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.

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.
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 we 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 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 we 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 Enable batch job events publishing.

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.

See the documentation for .

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 we specify the --wait argument, the utility outputs the following return codes about the status of the job we 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 we 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 we 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.

Enable the batchManagement-1.0 and zosLocalAdapters-1.0 features in server.xml.

<featureManager>
	<feature>batchManagement-1.0</feature>
	<feature>zosLocalAdapters-1.0</feature>
</featureManager>

Configure a zosLocalAdapters-1.0 endpoint. The following example illustrates a zosLocalAdapters-1.0 endpoint configuration.
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, we 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 we must use to grant read access to the resource.
Note: In this example, bob is the user running batchManagerZos.
If we want batchManagerZos requests to run on the server under the client's identity, we must authorize the server to use SAFCRED z/OS authorized resources. The following example illustrates the RACF commands that we must use to enable the server to use SAFCRED z/OS authorized resources.
Start the Angel address space.
Start the Liberty server.
Use the ping command to test connectivity between the batchManagerZos client and the Liberty server.
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.
To troubleshoot, we 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 using rest and without a queue manager subscription.
Optional: Configure the batchManagerZos client utility to wait for a batch job event to exit, instead of waiting using polling.
Configure the batch server to enable the publishing of job-related events that use WebSphere MQ messaging provider.
See the documentation for Enable batch job events publishing. Use the example in step 8, we can submit a job and wait for its complete by a job end event by adding the following:
From the client side, we 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 using the following properties:
We can use a managed queue for the subscription to the job events that you specified on our WebSphere Application Server for z/OS system using the queueName property. We can specify a non-default topic root for the server to use using the topicRootproperty. The batchManagerZos client waits to receive one of three events that represents a job instance ended state:
1. Optional: 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.