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>]
- /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
- Content-Type
- One of the following values:
- 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).
- Set to
Custom headers
- 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 that specifies 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. The correlator 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 results 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 that follow 'X-IBM-JCL-Symbol-' up to the colon separator (:) form the
symbol name. The data that follows 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 nameMBR
with valueABC
. Specifying this custom header and submitting a job that uses//MYDD DSN=MY.DATASET(&MBR.),DISP=SHR
in the JCL will causeABC
to be substituted as the member name.If this header is specified when JES3 is the primary job entry subsystem, an error results and no job is submitted.
For more information on JCL symbols, see Using system symbols and JCL symbols in z/OS MVS™ JCL Reference.
- X-IBM-Notification-URL
- Specifies a destination URL for receiving an HTTP
POST when any of the job events specified in
X-IBM-Notification-Options
happen. IfX-IBM-Notification-Options
is not specified, the destination URL receives 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 notification document. - X-IBM-Notification-Options
- Specifies the events of a submitted job. This header consists of a JSON string with a single
property called
events
. The value of theevents
property is a list of strings that indicates the job events which trigger HTTP POSTs. If any of the job events happen, the destination URL specified inX-IBM-Notification-URL
receives an HTTP POST. Valid event types areready
,active
, andcomplete
and are case-insensitive. The maximum number of characters is 4096. If no values or invalid event types are provided, an exception occurs.Ready
- Job is ready for execution.Active
- Job started execution.Complete
- Job completed execution.
This header is only valid if you are using JES2 EDS for job notifications over HTTP. It will not take effect if you are using the Common Information Model (CIM) jobs indication provider.
If this header is specified, the header
X-IBM-Notification-URL
must also be specified, otherwise it is ignored.Example:X-IBM-Notification-Options: {"events": ["active", "ready", "complete"]}
- X-IBM-Intrdr-File-Encoding
- This optional header specifies that the EBCDIC code page is to be used for encoding the data
that is written to the internal reader. If not specified, the default is IBM-1047. This header is
ignored when optional header X-IBM-Intrdr-Mode is set to RECORD or BINARY.
This header is effective only when the JCL for the job to be submitted is included in the HTTP request body. This header is ignored when the job to be submitted resides in a data set or UNIX file.
- X-IBM-Target-System = <string>
- This 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
andX-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. - X-IBM-Target-System-User
- This 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. BothX-IBM-Target-System-Password
andX-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:- The
X-IBM-Target-System-User
header was provided in a previous request - The service described in Authenticate with a secondary z/OSMF instance was issued in a previous request.
- The
- X-IBM-Target-System-Password
- This 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. BothX-IBM-Target-System-Password
andX-IBM-Target-System-User
must be provided together; otherwise, this header is ignored.
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.
- 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.
Code page 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
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 Controlling job submission in z/OS JES2 Initialization and Tuning Guide or Authorizing the Use of Input Sources in z/OS JES3 Initialization and Tuning Guide.
Usage considerations
See Usage considerations for the z/OSMF REST services.
- 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
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
Location of the job | Example |
---|---|
Partitioned data set (fully qualified) |
|
Partitioned data set (non-fully qualified) |
|
Sequential data set |
|
UNIX file |
|
Example of a request that contains the job JCL
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