Submit a job

You can use this operation to submit a job to run on z/OS.

HTTP method and URI path

PUT /zosmf/restjobs/jobs[/-<JESB>]

where:

/zosmf/restjobs/jobs/ identifies the z/OS® jobs REST interface.
<JESB> represents an optionally-specified secondary JES subsystem. If you omit this value, the request is processed by the primary JES subsystem.

Standard headers

Use the following standard HTTP header with this request:

Content-Type

One of the following values, as appropriate:

Set to text/plain when the optional header X-IBM-Intrdr-Mode is set to TEXT or is omitted, and the job JCL is included in the request.
Set to application/octet-stream when optional header X-IBM-Intrdr-Mode is set to RECORD or BINARY, and the JCL for the job to be submitted is included in the HTTP request.
Set to application/json when the job to be submitted resides in a data set or UNIX file, which is identified in a JSON document (included as input with this request).

Custom headers

Optionally, you can include one of the following custom HTTP headers with this request:

X-IBM-Intrdr-Class

A single character that specifies the internal reader class; the default is A. This value defines the default message class (MSGCLASS) for the job.

X-IBM-Intrdr-Recfm

A single character that specifies the internal reader record format: F or V.

When submitting a job from a data set, you can omit this header. Otherwise, this value must match the record format of the data set.

When not submitting a job from a data set, if you omit this header or specify a value other than F or V, the default of F is used.

X-IBM-Intrdr-Lrecl

An integer value specifying the internal reader logical record length (LRECL).

When submitting a job from a data set, you can omit this header. Otherwise, this value must match the LRECL of the data set.

When not submitting a job from a data set, if you omit this header or specify a non-integer value, the default of 80 is used.

X-IBM-Intrdr-Mode

A keyword that specifies the format of the input job: TEXT, RECORD, or BINARY.

When submitting a job from a data set, you can omit this header. Otherwise, this value must be set to RECORD.

When not submitting a job from a data set, observe the following rules:

If you omit this header, the TEXT keyword is used by default.
If you specify the BINARY keyword, the X-IBM-Intrdr-Recfm header must be omitted or set to F (the default).
If you specify the RECORD keyword or BINARY keyword, you must set Content-Type to application/octet-stream.

X-IBM-User-Correlator

Specifies the user portion of the job correlator. In z/OS, a job correlator can be used to associate each job with a unique 64-character value, which provides you with a means to query a job in the system and track it through execution.

A job correlator consists of a 31-byte system-defined portion and a colon character (:), followed by a 32-byte user portion. The system-defined portion contains the following values:

8-byte job ID
8-byte MAS name for the system on which the job resides
8-byte sequence value
7-bytes of reserved space.

Following the system value is the colon character (:) separator and the second string: an optional 32-character user-defined value (the user portion). This value is 1 – 32 characters in length, where the first character must be uppercase alphabetic (A-Z) or special ($, #, @). The remaining characters (up to 31) can be any combination of uppercase alphabetic, numeric (0-9), or special. Blank characters are not supported.

If specified, the user portion is combined with the system portion, producing the full job correlator that will be returned in the job-correlator property of the JSON job document. If the user portion is not specified, the returned job correlator is the 32-byte system value, ending with the colon (:).

If this header is specified when JES3 is the primary job entry subsystem, an error will result and no job is submitted.

For more information on the job correlator, see z/OS JES2 Commands.

X-IBM-JCL-Symbol-name

Specifies the name and value for a JCL symbol. The symbol name is included in the header, at the name position. The characters following 'X-IBM-JCL-Symbol-' up to the colon separator (:) form the symbol name. The data following the colon specifies the value for the symbol.

A symbol name is 1 – 8 characters, where the first character must be uppercase alphabetic (A-Z) or special ($, #, @). The remaining characters (up to 7) can be any combination of uppercase alphabetic, numeric (0-9), or special.

A symbol value is limited to 255 characters. Multiple symbol names and values can be specified, up to a limit of 128.

Example: X-IBM-JCL-Symbol-MBR: ABC specifies symbol name MBR with value ABC. Specifying this custom header and submitting a job that uses //MYDD DSN=MY.DATASET(&MBR.),DISP=SHR in the JCL will cause ABC to be substituted as the member name.

If this header is specified when JES3 is the primary job entry subsystem, an error will result and no job will be submitted.

For more information on JCL symbols, see z/OS MVS JCL Reference.

X-IBM-Notification-URL

Specifies a destination URL for receiving an HTTP POST when the job is no longer eligible for execution (that is, when the job reaches the output queue or purge queue). The notification is in the form of a JSON document (Content-Type: application/json), which contains job status information. For the contents of the JSON document, see Job completed document.

Query parameters

None.

Input to this request

Internet media type: text/plain, application/octet-stream, or application/json
HTTP request with optional headers, followed by job to be submitted or a JSON document identifying the location of the job to be submitted (a data set or UNIX file).

To submit a job, you can include the job JCL in the HTTP request itself, or you can have the request refer to a job that resides in a data set or UNIX file. Here, you include a JSON document ("Content-Type: application/json" with the HTTP request. The JSON document contains the property “file”:“<file-name>” where <file-name> identifies the data set or UNIX file that contains the job to be submitted.

Use the JSON document to identify the data set or UNIX file containing the job to be submitted, as follows:

For a data set, specify the qualified data set name, prefixing the data set name with two leading forward slash characters (“//”).
If not fully qualified, the current z/OSMF user ID is prefixed to the data set name. Supported data set types include sequential data sets and members of partitioned data sets.

Data sets must be catalogued.
For a z/OS UNIX file, specify the absolute path name of the file.
Codepage conversion is not performed on the contents of the file.

For a migrated data set, this operation does not cause the data set to be retrieved, unless you specify otherwise. To request that a data set be recalled without waiting, you can specify the “recall” property with the value “yesnowait” to the input JSON document. Unique error responses are provided when a migrated data set is requested to be recalled without waiting and for when a migrated data set is not requested to be recalled. In both cases, no job is submitted. If you have asked for a recall, without waiting, when you try the submit again, you should do so without adding the “recall” property to the JSON document or by changing the “recall” property to the value “no.”

Required authorizations

See Required authorizations.

In addition, your user ID must be authorized to run jobs on the system and be able to access any protected resources that the job might require. For information about the security considerations for job submission, 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, observe the following considerations for this request:

This request can be directed to a secondary JES subsystem. To do so, use the following request format:
```
https://host:port/zosmf/restjobs/jobs/-JESB
```
where JESB is the name of the secondary JES subsystem in these examples.

Expected response

On completion, the z/OS jobs REST interface returns an HTTP response with a JSON job document. For the contents, see Job document.

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

Example of submitting a job from a data set or UNIX file

Table 1 shows variations of a PUT request that submits the job TESTJOBX to run on z/OS. In each variation, the PUT request contains a JSON statement that identifies the location of the job to be submitted.

Table 1. Variations of a PUT request for submitting a job from a data set or UNIX file.
Location of the job	Example
Partitioned data set (fully qualified)	`PUT /zosmf/restjobs/jobs HTTP/1.1 Content-Type: application/json X-IBM-Intrdr-Class: A { “file” : “//'MYJOBS.TEST.CNTL(TESTJOBX)'” }`
Partitioned data set (non-fully qualified)	`PUT /zosmf/restjobs/jobs HTTP/1.1 Content-Type: application/json X-IBM-Intrdr-Class: A { “file” : “//TEST.CNTL(TESTJOBX)” }`
Sequential data set	`PUT /zosmf/restjobs/jobs HTTP/1.1 Content-Type: application/json X-IBM-Intrdr-Class: A { “file” : “//'MYJOBS.TEST.JOB1'” }`
UNIX file	`PUT /zosmf/restjobs/jobs HTTP/1.1 Content-Type: application/json X-IBM-Intrdr-Class: A X-IBM-Intrdr-Recfm: V X-IBM-Intrdr-Lrecl: 255 X-IBM-Intrdr-Mode: TEXT { “file” : “/u/myjobs/job1” }`

Example of a request that contains the job JCL

The following request submits the job TESTJOBX to run on z/OS. Here, the JCL for the job to be submitted is contained in the PUT request.

PUT /zosmf/restjobs/jobs HTTP/1.1
Host: zosmf1.yourco.com
Content-Type: text/plain
X-IBM-Intrdr-Class: A
X-IBM-Intrdr-Recfm: F
X-IBM-Intrdr-Lrecl: 80
X-IBM-Intrdr-Mode: TEXT

//TESTJOBX JOB (),MSGCLASS=H
// EXEC PGM=IEFBR14

A sample response is shown in Figure 1.

Figure 1. Example: Returned results of a job submission

HTTP/1.1 201 Created
Date: Fri, 17 Jan 2014 05:39:28 +0000GMT
Content-Type: application/json
Connection: close

{
"jobid":”JOB00025”,"jobname":"TESTJOBX",”subsystem”:null,"owner":"IBMUSER",
"status":"INPUT","type":"JOB","class":"A",”retcode”:null,
"url":"https:\/\/host:port\/zosmf\/restjobs\/jobs\/TESTJOBX\/JOB00025",
"files-url":"https:\/\/host:port\/zosmf\/restjobs\/jobs\/TESTJOBX\/JOB00025\/files"
}