For z/OS platforms

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.
    batchAdmin:     BBGZDFLT.com.ibm.ws.batch.batchAdmin
    batchSubmitter: BBGZDFLT.com.ibm.ws.batch.batchSubmitter
    batchMonitor:   BBGZDFLT.com.ibm.ws.batch.batchMonitor
The requestor'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 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.
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>.
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.

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

    The following example shows how to submit a job and wait for its completion by a job end event:
    $ 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  
    --queueManagerName=[name of MQ queue manager]
    The batchManagerZos client waits to receive 1 of 3 events that represents a job instance ended state:
    batch/jobs/instance/stopped 
    batch/jobs/instance/failed 
    batch/jobs/instance/completed

Icon that indicates the type of topic Task topic



Timestamp icon Last updated: Friday, 16 September 2016
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-dist&topic=twlp_batchManagerZos
File name: twlp_batchManagerZos.html