JSON document specifications for z/OS jobs REST interface requests

This section describes the contents of the JSON documents that are used with z/OS® jobs REST interface requests.

The following JSON documents are described:

Job document
Job completed document
Job feedback document
Job file document
Error report document.

Job document

Table 1 shows the contents of the JSON job document.

Table 1. Contents of the JSON job document
Property	Description
jobid	Job ID.
jobname	Job name.
subsystem	The primary or secondary JES subsystem. If this value is null, the job was processed by the primary subsystem.
owner	The z/OS user ID associated with the job.
status={ INPUT\| ACTIVE\| OUTPUT }	Job status. One of the following values: INPUT Job is in input processing. ACTIVE Job is running. OUTPUT Job is on the hardcopy output queue. If this value is null, the job status could not be determined.
type={ JOB\| STC\| TSU }	Job type. One of the following values: JOB Batch job. STC Started task. TSU TSO/E user.
class	Job execution class.
retcode={ ABENDUnnnn \| ABEND Sxxx \| CANCELED \| CC nnnn \| CONV ABEND \| CONV ERROR \| JCL ERROR \| SEC ERROR \| SYS FAIL }	Job completion code. One of the following values: ABENDUnnnn Job ended with the user abend code nnnn. ABEND Sxxx Job ended with the system abend code xxx. CANCELED Job was canceled. CC nnnn Job ended with the completion code nnnn. CONV ABEND Converter ended abnormally when processing the job. CONV ERROR Converter error when processing the job. JCL ERROR Job encountered a JCL error. SEC ERROR Job failed a security check. SYS FAIL System failure. If this value is null, the job has not yet completed.
url	Resource URL based on original HTTP request.
files-url	Resource URL for listing the spool files for the job.
job-correlator	Job correlator. If this value is null, the job was submitted to JES3.
phase	Job phase. Provides a numeric indicator of the current state of the job.
phase-name	Job phase name. Provides a text description of the specific phase of the job.
reason-not-running	Text identifying one or more reasons why the job is not running.

Job completed document

Table 2 shows the contents of the JSON job completed document.

Table 2. Contents of the JSON job completed document
Property	Description
job-correlator	Job correlator. If this value is null, the job was submitted to JES3.
jobid	Job ID.
jobname	Job name.
owner	The z/OS user ID associated with the job.
class	Job execution class.
retcode={ ABENDUnnnn \| ABEND Sxxx \| CANCELED \| CC nnnn \| CONV ABEND \| CONV ERROR \| JCL ERROR \| SEC ERROR \| SYS FAIL }	Job completion code. One of the following values: ABENDUnnnn Job ended with the user abend code nnnn. ABEND Sxxx Job ended with the system abend code xxx. CANCELED Job was canceled. CC nnnn Job ended with the completion code nnnn. CONV ABEND Converter ended abnormally when processing the job. CONV ERROR Converter error when processing the job. JCL ERROR Job encountered a JCL error. SEC ERROR Job failed a security check. SYS FAIL System failure.
completion-type	Specific completion type: 0 No completion information was received. 1 Job ended normally. 2 Job ended with a completion code. 3 Job encountered a JCL error. 4 Job was canceled. 5 Job abended. 6 Converter error when processing the job. 7 Job encountered a security error. 8 Job failed in EOM. 9 Job failed a security check. 10 System failure.
completion-code	Completion code. Set for completion-type values 1 and 2. Otherwise null.
abend-code	Job completed with abend code. Set for completion-type values 5 and 8. Otherwise null. When set, one of the following values: Unnnn Job ended with the user abend code nnnn. Sxxx Job ended with the system abend code xxx.

Job feedback document

Table 3 shows the contents of the JSON job feedback document.

Table 3. Contents of the JSON job feedback document
Property	Description
jobid	Job ID.
jobname	Job name.
original-jobid	Original job ID. If the job was processed on another system, this value represents the original job identifier that was assigned when the job was submitted on the host system. If the target system cannot assign the original job identifier, the target system assigns a new ID to the job, which is indicated as "jobid" in this document.
owner	z/OS user ID associated with the job.
member	JES2 multi-access spool (MAS) member name.
sysname	z/OS system name.
job-correlator	Job correlator. If this value is null, the job was submitted to JES3.
status={n}	job processing status. If set to zero (0), the request was processed successfully. Otherwise, there was an error. See the message property for a description of the error.
internal-code	If job processing status indicates an error (a value other than 0), this property contains the internal service routine return code. Otherwise, this property is omitted.
message	If job processing status indicates an error (a value other than 0), this property contains a description of the error. Otherwise, this property is omitted.

Job file document

Table 4 shows the contents of the JSON job file document.

Table 4. Contents of the JSON job file document
Property	Description
jobname	Job name.
recfm	Record format of the file. The first character of the returned string is one of the following: F Fixed length records V Variable length records U Undefined length records. One or more subsequent characters might also be present in the returned string (in this order): B File has blocked records S File has standard records (if fixed length format) or spanned records (if variable length format) M File has machine print-control characters A File has ASA (ANSI) print-control characters. Generally, the B (blocked) and S (standard or spanned) characters are not present for JES spool files. Also, the M (machine) and A (ASA) characters are mutually exclusive.
byte-count	Number of bytes on spool consumed by the spool file. The value can be zero (0). This field is integer data type.
record-count	Number of records in the spool file. The value can be zero (0). This field is integer data type.
job-correlator	Job correlator. If this value is null, the job was submitted to JES3.
class	Class assigned to the spool file.
jobid	Job ID.
id	Data set number (key). This field is integer data type.
ddname	DDNAME for the data set creation.
records-url	Resource URL for retrieving the spool file contents for the job.
lrecl	Specifies the length, in bytes, for fixed-length records and the maximum length for variable-length records.
subsystem	The primary or secondary JES subsystem. If the value is null, the job was processed by the primary subsystem.
stepname	Step name for the step that created this data set. The value can be null.
procstep	Procedure name for the step that created this data set. The value can be null.

Error report document

Table 5 shows the contents of the JSON error report document.

Table 5. Contents of the JSON error report document
Property	Description
category	Error category. This field is integer data type.
rc	Return code. This field is integer data type.
reason	Reason code. This field is integer data type.
message	Message that describes the error.
details	(optional) Array of strings containing additional message details.
stack	Stack trace of the exception.

For the meanings of the category, rc, and reason fields, see Error reporting categories.