Skip to content

Batch Job Processing Options

Handling ZMF Calls that Run Asynchronously Via a Batch Job

Many ZMF Services run in batch jobs. A call for these services results in a message indicating the process was initiated, but the process does not complete until a file tailoring process is run, and the resulting job has run to completion. This can be problematic if you are using Rest Services to create pipelines that require a process to complete before initiating the next process.

To address this, Wait/Timeout options are available for all ZMF services that run in batch jobs through Rest Extensions. When wait is requested, Rest Services determines the JOBNAME/JOBID of the Batch process and waits for the JOB to complete before returning a response to the client.

All batch processes are updated with the following request parameters:

waitForCompletion = Y/N/J

Parameter values:

N – Do not wait for job to complete (the default).

Y – Wait for Job to complete.

J – Wait for File tailoring to complete.

waitTimeout = value

where value indicates how long to wait for process completion (in minutes). The default value is 10.

When a wait option is specified, the response will be updated. The following tags may be present if processing is bypassed or an error condition occurs during processing:

extensionBypassMessage – A message indicating the reason wait processing was bypassed.

extensionErrorMessage – A message indicating an error occurred during wait processing.

The following tags are added as a result tag (array). If multiple jobs are submitted, more than one result may be returned.

jobname – The jobname

jobid – The jobid

The following tags are added only if WAIT=Y is specified:

jobComplete – Indicates whether the job ran to completion (true or false).

completioncode – The job completion code (set only when jobComplete = true).

errormessage – An error occurred obtaining job status about the job.

joblaststatus – The last job status when job has not completed.

Wait processing is supported for the following Package Services: Audit, Backout, Revert, Promote, Demote, Freeze.

Wait processing is also supported for the following Component Services: Build, Recompile, Relink, Rebuild.

The following example illustrates how the response may be updated. This sample shows the response to a batch checkout with waitForCompletion=Y specified.

{
    "message": "CMN8704I - Checkout service submitted",
    "reasonCode": "8704",
    "returnCode": "0",
    "result": [
        {
            "jobname": "WSER27B",
            "jobid": "J0616061",
            "jobComplete": true,
            "completioncode": "0"
        }
    ]
}

Be sure to configure HTTP client timeout values when using wait options

Be sure to configure HTTP Clients with an appropriate socket timeout value. These calls may not work properly if default values are used. For example, the Apache HTTP Client uses a default socket timeout of 5 minutes. If this value is unchanged, socket timeout conditions are reflected back to the client and the response from Rest Services will never be received. Rest Services may issue a "Client Closed Connection" message when this occurs.

Default Job Cards

To simplify Job Card processing, you can use the Rest Services DEFAULT_JOBCARDS option to provide default job cards for all batch processes. Default Job Card processing is enabled by specifying the following parameter in ZMFPARMS:

DEFAULT_JOBCARDS=Y/N

The default is N.

Template Job cards with variables can be specified in ZMFPARMS to further customize processing. Default values are shown below.

JOBCARD1=//&USERJOB& JOB 0,'&API&',CLASS=A,MSGCLASS=X
JOBCARD2=//* JOB SUBMITTED BY &USERID& THROUGH REST SERVICES
JOBCARD3=//*
JOBCARD4=//*

The following variables can be specified in the ZMFPARMS JOBCARD parameters.

&USERJOB& - A JOBNAME consisting of the userid and a random 1 character suffix (A-Z).

&USERID& - The user submitting the request.

&API& - The name of the currently running API (build/freeze - etc).

When found in the templates, these variables are replaced with values from the current environment.