
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 requestor's identity (the JEE 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 requestor's identity for the batch request.
- Batch role-based authorization
If appSecurity is enabled in the server, you must assign the requestor'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 using SAF authorization, the SAF authorization provider determines the authorization of the requestor'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.
The requestor's identity must be granted READ access to the appropriate resource profile to be authorized to the corresponding batch role.batchAdmin: BBGZDFLT.com.ibm.ws.batch.batchAdmin batchSubmitter: BBGZDFLT.com.ibm.ws.batch.batchSubmitter batchMonitor: BBGZDFLT.com.ibm.ws.batch.batchMonitorThe 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 submitting a batch job by using the batchManagerZos client utility, the jobParametersFile and jobPropertiesFilesupports the use of multiple files 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.
As an example, --jobParametersFile=<filepath1> would override --jobParametersFile=<filepath1>,<filepath2> in the control properties file. The resulting parameter is --jobParametersFile=<filepath1>.jobParametersFile=filePath1,filePath2,filePath3 jobPropertiesFile=filePath1,filePath2,filePath3
- 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.
- 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 will not match the return code from batchManagerZos. BPXBATCH takes the batchManagerZos return code and shifts it up by one byte. For example, if batchManagerZos returns 1, then BPXBATCH returns 256, which is the hex value 0x01, shifted up one byte to 0x100.If you call BPXBATCH from a JCL STEP, the STEP return code is truncated to the lower three hex characters of the return code from BPXBATCH. For example, if batchManagerZos returns 35, which is 0x23 hex, the BPXBATCH will return 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.
Task topic