Cancel a job and purge its output

You can use this operation to cancel a job and purge its output.

HTTP method and URI path

DELETE /zosmf/restjobs/jobs/<jobname>/<jobid>
DELETE /zosmf/restjobs/jobs/<correlator>

where:

/zosmf/restjobs/jobs/ identifies the z/OS® jobs REST interface.
<jobname>/<jobid> identifies the job to be canceled. Use either the job name and job ID combination or the job correlator to identify the job.
<correlator> identifies the job to be canceled. Use either the job name and job ID combination or the job correlator to identify the job.
To use a job correlator on this request, specify the full job correlator for the job: The 31-byte system portion, a semicolon, and the user portion (up to 32 bytes). The correlator can be one that you have obtained from the "job-correlator" property in a returned JSON job document. Alternatively, you can specify the complete URL as provided in the "url" property of a JSON job document.

Custom headers

You can include the following optional custom HTTP header with this request:

X-IBM-Job-Modify-Version

Use this header to specify whether the request is to be processed asynchronously or synchronously, as follows:

1.0: Specifies that the request is to be processed asynchronously. In response, the caller receives an HTTP status code of 202 Accepted, with no indication of the success or failure of the request. To verify that the initial request was performed, the caller can issue the service described in Obtain the status of a job.
2.0: Specifies that the request is to be processed synchronously. In response, the caller receives an HTTP status code, which indicates the results of the request. For a successful request, the caller also receives the JSON job feedback document, which includes details about the job that was cancelled.

If this header is omitted, the request is processed asynchronously by default.

Synchronous processing is supported for JES2 only. On systems running JES3, the z/OS jobs REST interface services must run asynchronously.

For an example of how this header is specified, see Example request.

Query parameters

None.

Required authorizations

See Required authorizations.

In addition, your user ID must be authorized to cancel the job on the system, which allows the user to delete the job SYSOUT data sets. For information about the security considerations for job cancellation, see z/OS JES2 Initialization and Tuning Guide, SA22-7532, or z/OS JES3 Initialization and Tuning Guide, SA22-7549.

Usage considerations

See Usage considerations for the z/OSMF REST services.

In addition, note that this request can be directed to a secondary JES subsystem. To do so, use the following URL format:

https://host:port/zosmf/restjobs/jobs/-JESB/jobname/jobid

where JESB is the name of the secondary JES subsystem. A request to a secondary JES subsystem must include the job name and job id, rather than a job correlator.

Expected response

The response depends on whether the request is processed synchronously or asynchronously, as follows:

For an asynchronous request, the caller receives only the HTTP status code 202 ACCEPTED. To determine whether the request was successful, the caller can issue the service described in Obtain the status of a job.
For a synchronous request, the caller receives an HTTP status code, which indicates the results of the request, as follows:
- Status code 200 indicates that the synchronous request was processed successfully. This status, however, does not mean that the operation was successful. To determine the success of the operation, check the "status" property in the JSON job feedback document for a value of 0 (zero). See Job feedback document.
- Status code of 4nn or 5nn indicates that an HTTP error has occurred.

For HTTP errors, z/OS jobs REST interface returns error information as a JSON error report document. See Error report document.

Example request

The following request cancels the job TESTJOBW, job ID JOB00085 and purges its output on the z/OS system. With the inclusion of the X-IBM-Job-Modify-Version header set to 2.0, the request is eligible to be processed synchronously, if supported on the target JES subsystem.

DELETE /zosmf/restjobs/jobs/TESTJOBW/JOB00085 HTTP/1.1
X-IBM-Job-Modify-Version: 2.0

Example response

A sample response is shown in Figure 1. Because the request was processed synchronously by the target JES subsystem, the response body includes the job feedback document with details about the job that was cancelled.

Figure 1. Example: Results of a job delete request

HTTP/1.1 200 OK
Date: Thu, 16 Jan 2014 05:39:28 +0000GMT
Content-Type: application/json
Connection: close

{
"jobid":"JOB00085",
"jobname":"TESTJOBW",
"original-jobid":"JOB00085",
"owner":"IBMUSER"
"member":"JES2",
"sysname":"SY1",
"job-correlator":"J0000085SY1.....CC20F380.......:",
"status":"0"
}