Release a job

For a job that has been held from execution on z/OS, you can use this operation to release the job. When released, a job is made eligible for selection to execute.

HTTP method and URI path

PUT /zosmf/restjobs/jobs/<jobname>/<jobid>
PUT /zosmf/restjobs/jobs/<correlator>
where:
  • /zosmf/restjobs/jobs/ identifies the z/OS® jobs REST interface.
  • Start of changeTo identify the job in the request, use either the combination of the job name and job ID, or the job correlator, as follows:
    • <jobname>/<jobid> identifies the job to be released.
    • <correlator> identifies the job to be released. 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 obtained from the "job-correlator" property in a returned JSON job document.
    End of change

Custom headers

Start of changeX-IBM-Target-System = <string>End of change
Start of changeThis header indicates the target system name (nick name) for this request, where the system name (nick name) is defined in the local system Systems table. The target host system must support single-sign-on by using either an LTPA token or a valid X-IBM-Target-System-User and X-IBM-Target-System-Password is provided for the target system. If the target system is the local system, this header is ignored and has no effect.End of change
Start of changeX-IBM-Target-System-UserEnd of change
Start of changeThis header indicates the z/OS user ID that allows the user to access the target system. If the X-IBM-Target-System header is not supplied, this header is ignored. Both X-IBM-Target-System-Password and X-IBM-Target-System-User must be provided together; otherwise, this header is ignored.
If this header is not provided in the current request, the current request uses the authenticated user credentials to access the target system if either of the following conditions are true:
End of change
Start of changeX-IBM-Target-System-PasswordEnd of change
Start of changeThis header indicates the password that is associated with the z/OS user ID. If the X-IBM-Target-System header is not supplied, this header is ignored. Both X-IBM-Target-System-Password and X-IBM-Target-System-User must be provided together; otherwise, this header is ignored.End of change

Query parameters

None.

Input to this request

  • Internet media type: application/json
  • HTTP request with JSON document containing the following properties:
    "request":"release"
    Indicates a request to release a job.
    "version":"n.n"
    Specifies the version of the service to be used, either 1.0 or 2.0.

Start of changeTo request asynchronous processing for this service, set the "version" property to 1.0. To request synchronous processing (the default), set "version" to 2.0 or omit the property from the request. If so, the system will attempt to process the request synchronously, if such processing is supported on the target JES subsystem.End of change

For further considerations, see Synchronous support for the job modify operations.

Required authorizations

See Required authorizations.

Usage considerations

See Usage considerations for the z/OSMF REST services.

In addition, observe the following consideration for this request:
  • This request can be directed to a secondary JES subsystem. To do so, use one of the following request formats: 
    https://host:port/zosmf/restjobs/jobs/-JESB/jobname/jobid
https://host:port/zosmf/restjobs/jobs/-JESB/correlator
    where:
    • JESB is the name of the secondary JES subsystem.
    • The job to be released is identified by either the job name and job ID (jobname/jobid) or the job correlator (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 errors, z/OS jobs REST interface returns error information as a JSON error report document. See Error report document.

Example request

The following request specifies that the job TESTJOBW, job ID JOB00023, is to be released. With the inclusion of the "version" property set to 2.0, the request is eligible to be processed synchronously, if supported on the target JES subsystem. 
PUT /zosmf/restjobs/jobs/TESTJOBW/JOB00023 HTTP/1.1
Host: zosmf1.yourco.com
Content-Length: 40
Content-Type: application/json

{
"request":"release"
"version":"2.0"
}

Example response

A sample response is shown in Figure 1.
Figure 1. Example: Returned results of a job release request
HTTP/1.1 200 OK
Date: Thu, 16 Jan 2014 05:39:28 +0000GMT
Content-Type: application/json
Connection: close

{
"jobid":"JOB00023",
"jobname":"TESTJOBW",
"original-jobid":"JOB00023",
"owner":"IBMUSER"
"member":"JES2",
"sysname":"SY1",
"job-correlator":"J0000023SY1.....CC20F378.......:",
"status":"0"
}