
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.
The requester'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.batchMonitor
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.
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
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:
- Job parameter control properties are loaded and merged. These properties are structured as --jobParameter=key=value inside of the control properties file.
- The contents of the files that are referenced by the --jobParametersFile parameter are loaded and merged.
- 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:
- 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.
- Job parameter control properties are loaded and merged. These properties are structured as --jobParameter=key=value inside of the control properties file.
- 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.- If the --jobParametersFile parameter is included as a command line
parameter, the following actions occur in order of ascending precedence:
- 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.
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 .
- 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.