Error reporting categories

This section describes the error categories and associated error codes that can be returned in the JSON error report document, described in Error report document.

Table 1. Error categories for z/OS jobs REST interface operations
Category	Ordinal Value	Description	Where the error details are described
Dynalloc	1	Dynamic allocation errors.	Category 1 — Dynamic allocation error
VSAM API	3	Errors produced or detected by the Java/ JNI/ C/ HLASM/ VSAM layer.	Category 3 — VSAM API error
VSAM system	4	Errors produced or detected by VSAM. The return code and reason code are VSAM specific.	Category 4 — VSAM system error
VSAM ABEND	5	ABEND information resulting from VSAM failures.	Category 5 — VSAM ABEND error
Service	6	Errors produced or detected in the service layer.	Category 6 — Service error
Unexpected	7	Unexpected errors detected.	Category 7 — Unexpected error
SSI extended status	8	Errors produced or detected by the extended status function call of the subsystem interface (SSI Function Code 80).	Category 8 — SSI extended status error
CIM	9	Errors produced or detected by the CIM interface.	Category 9 — Common Information Model (CIM) error
SSI job modify	10	Errors produced or detected by the job modify function call of the subsystem interface (SSI Function Code 85).	Category 10 — SSI job modify error

Category 1 — Dynamic allocation error

Table 2 shows the possible conditions for this error category.

Table 2. Category 1 errors
rc	reason	message	Description
n	0	`Error allocating internal reader, RC=%d (0x%08X)`	An error occurred when z/OS attempted to allocate the internal reader for job submission. In the message, `RC` is error data from the dynamic allocation request (SVC 99). To diagnose the error, convert the `RC` value from decimal to a 4-byte hexadecimal value, which provides the dynamic allocation error code and info code, as follows: High-order two bytes indicate the error code from the dynamic allocation request (field S99ERROR in the input request block S99RB). Low order two bytes indicate the info code from the dynamic allocation request (field S99INFO in the input request block S99RB). For information about dynamic allocation and the meanings of the error code and info code, see z/OS MVS Programming: Authorized Assembler Services Guide.
n	1	`Error allocating input data set: %s, RC=%d (0x%08X)`	An error occurred when z/OS attempted to allocate a ddname for the data set specified as the source for the input job. In the message, `RC` is the return code from the BPXWDYN service. For information about BPXWDYN and the meaning of the return code, see z/OS Using REXX and z/OS UNIX System Services.
n	2	`Error allocating spool file: job '%s' spool file id %d, RC=%d (0x%08X)`	An error occurred when z/OS attempted to allocate the requested spool file. Perhaps a thread is attempting to allocate the spool file while another thread is requesting that the job be canceled and its output purged. In the message, `RC` is error data from the dynamic allocation request (SVC 99). Both decimal and hexadecimal values are provided in the message. The hexadecimal value provides the dynamic allocation error code and info code, as follows: High-order two bytes indicate the error code from the dynamic allocation request (field S99ERROR in the input request block S99RB). Low order two bytes indicate the info code from the dynamic allocation request (field S99INFO in the input request block S99RB). For information about dynamic allocation and the meanings of the error code and info code, see z/OS MVS Programming: Authorized Assembler Services Guide.

Category 3 — VSAM API error

Table 3 shows the possible conditions for this error category.

Table 3. Category 3 errors
rc	reason	message	Description
4	1	`Incorrect JesVsam handle`
4	2	`VSAM file is not open`
4	3	`Record length %d > lrecl %d`	Writing a record to a VSAM file failed because an incorrect record length was specified.
4	4	`Could not write JCL to internal reader`	An I/O exception occurred when writing JCL to the internal reader.
8	0	`JesVsam get failed`	Buffer too small to hold the VSAM record.
255	0	`JesVsam native buffer malloc failed`

Category 4 — VSAM system error

Table 4 shows the possible conditions for this error category.

Table 4. Category 4 errors
rc	reason	message	Description
n	m	varies	For descriptions of the specific return and reason codes, see the VSAM publications.

Category 5 — VSAM ABEND error

Table 5 shows the possible conditions for this error category.

Table 5. Category 5 errors
rc	reason	message	Description
n	m	varies	The values n and m indicate the ABEND return code and reason code.

Category 6 — Service error

Table 6 shows the possible conditions for this error category.

Table 6. Category 6 errors
rc	reason	message	Description
4	1	`Incorrect Internal Reader mode: %s. Must be one of TEXT \| RECORD \| BINARY`	Request header X-IBM-Intrdr-Mode specified a value that is not valid. Valid values are TEXT, BINARY, or RECORD.
4	2	`Incorrect Internal Reader parameters: %s. Fixed records are required for binary mode`	The internal reader characteristics form a combination that is not valid. If you specify the value BINARY for the X-IBM-Intrdr-Mode request header, you must specify the value F for the X-IBM-Intrdr-Recfm request header.
4	3	`Request does not contain '%s' content`	Job modify requests must have a content type of application/json.
4	4	`Value of %s query parameter is not valid`	The query parameter identified in the message either contains incorrect characters or exceeds the allowable length. In the message, the query parameter is owner, prefix, jobid, or job-correlator.
4	5	`Update request is not 'cancel'`	The job modify request value for the "request" property is not valid. The value must be “cancel.”
4	6	`Request does not contain a valid job update request`	The job modify request input document does not specify a valid property. The valid properties are: “request” “class”
4	7	`No match for method %s and pathInfo='%s'`	The supplied servlet pathinfo does not match any expected string for the HTTP method that was specified.
4	8	`POST requests not supported`	For standard REST requests, the POST HTTP method is not allowed. To avoid this message, include the X-IBM-Requested-Method header to have the request sent through the POST verb.
4	9	`Job submission error. Record length %d too long for JCL submission, maxlen=%d`	The check for record mode job submission failed.
4	10	`No job found for reference: '%s'`	The job modify request specified a job that does not exist.
4	11	`Record range '%s' is not valid for spool file record request`	Request header X-IBM-Record-Range specified a value that is not valid. The content range must be specified using one the following formats: SSS-EEE where `SSS` identifies the start record and `EEE` identifies the end record to be retrieved. Both values are relative offsets (0-based). When `EEE` is set to 0, records through the end of the spool file are retrieved. SSS,NNN where `SSS` identifies the start record and `NNN` identifies the number of records to be retrieved.
4	12	`Job '%s' does not contain spool file id %d`
4	13	`Job input was not recognized by system as a job`	The job was submitted without a job statement or with unrecognized (non-JCL) content.
4	14	`Unsupported encoding: %s`	When submitting a job, the Content-Type request header specified a charset value that is not supported.
4	15	`DD names are not supported for submit input`	The value of the “filename” property in the JSON document provided on the submit job interface started with `//DD:` indicating the `dd:ddname` syntax. This is not supported.
4	16	`Data set not found`	The data set specified in the JSON document provided on the submit job interface was not found. It is possible the data set is not catalogued.
4	17	`Submit input data does not start with a slash`	This error occurs when the first character of the input job is not the EBCDIC slash character. Possible causes include: The Content-Type request header is set to `text/plain` when a JSON document naming the source of the input job is also used. The input data set or file does not contain EBCDIC data.
4	18	`Submit input filename must be absolute path: %s`	The z/OS UNIX file specification in the JSON document was not an absolute path.
4	19	`Internal reader mode must be RECORD for data set submission: %s`	If specified, the internal reader mode must be set to RECORD when submitting a job from a data set.
4	20	`Service not implemented: %s`	The requested service has not been implemented. The variable text `%s` contains additional information.
4	22	`Internal reader RECFM (%s) does not match data set RECFM (%s): %s`	If specified, the internal reader record format must match the record format of the existing data set when submitting a job from a data set.
4	23	`Internal reader LRECL (%d) does not match data set LRECL (%d): %s`	If specified, the internal reader logical record length must match the logical record length of the existing data set when submitting a job from a data set.
4	24	`Content type '%s' not valid for internal reader mode '%s'`	The values specified for Content-Type and internal reader mode are not a supported combination.
4	25	`JCL symbol name '%s' is not valid`	The specified symbol name does not match the syntax rules for a JCL symbol or start with the characters 'SYS'.
4	26	`JCL symbol '%s' value exceeds maximum length`	The value supplied for the specified symbol name exceeds the maximum value length of 255 characters.
4	27	`No value supplied for JCL symbol '%s'`	For a JCL symbol to be defined, it must have a non-null, non-blank value.
4	28	`Maximum number of JCL symbols exceeded`	An attempt to define more than 128 symbols has occurred.
4	29	`User correlator '%s' is not valid`	The specified user correlator (X-IBM-User-Correlator) does not match the syntax rules for a user correlator.
4	30	`Notification URL '%s' exceeds maximum length`	The specified notification URL exceeds the maximum value of 2083 characters.
4	31	`Request header not supported by primary JES subsystem: %s`	The request header identified in the message is not supported by the primary job entry subsystem.
4	32	`Error parsing JSON input`	When submitting a job, Content-Type specified `application/json`, but an exception occurred when attempting to process the input JSON document. Possible causes include: JCL stream was provided instead of a JSON document JSON document was malformed Required “file” property was not provided Value for the “recall” property was not valid. See the “stack” property of the JSON error report document for a message with additional information.
4	33	`Data set is migrated: %s`	The z/OS data set specified in the JSON document is migrated. No recall is issued. No job was submitted.
4	34	`Recall issued for migrated data set: %s`	The z/OS data set specified in the JSON document is migrated. A recall without waiting has been issued. No job was submitted.
4	35	`Error recalling data set, RC=%d`	An error occurred when attempting to recall a migrated data set. The return code from the ARCHRCAL service is included in the message. For details on ARCHRCAL and return codes from the DFSMShsm user macros, see z/OS DFSMShsm Managing Your Own Data.
4	36	`Incorrect internal reader class: %s. Must be one character in length.`	Internal reader class request header specified a value that is not valid. The class must be one character in length.
4	37	`Incorrect job update version requested: %s.`	The job modify request value for the “version” property or the X-IBM-Job-Modify-Version request header is not valid. The value must be `“1.0”` or `“2.0”`.
8	1	`Unable to query information about submitted job: %s`	The job status for the submitted job could not be obtained within the timeout period (3 seconds).
8	2	`EOF encountered before all requested bytes read (%d / %d)`	Internal read state error. The expected number of bytes were not available to be read before EOF
8	3	`Range start is beyond end of spool file %d for job %s`	During a request to get a range of records for a spool file, the X-IBM-Record-Range header specified a record start value that is beyond the end of the spool file.
8	4	`Cannot advance spool file more than Integer.MAX_VALUE. DD= %s`	During a request to get a range of records for a spool file, the X-IBM-Record-Range header specified a record start value greater than 2**31-1.
8	5	`Error opening input data set: %s`	An error occurred opening the input z/OS data set. See the “stack” property of the JSON error report document for a message with additional information.
8	6	`Error reading submit input data`	An error occurred reading the submit input data. See the “stack” property of the JSON error report document for a message with additional information.
8	7	`Error opening input file: %s`	An error occurred opening the input z/OS UNIX file. See the “stack” property of the JSON error report document for a message with additional information.
8	8	`IAZSYMBL error defining %s`	The JES symbol definition service (IAZSYMBL) failed while trying to define the specified information. In the message, `%s` is one of the following values: User correlator Notification URL One or more JCL symbols. For details about the IAZSYMBL error, see the “stack” property of the JSON error report document.
12	1	`Not authorized to access spool file`	An authorization check failed trying to OPEN the requested spool file.
12	2	`Not authorized to submit job`	Failed an authorization check when attempting to open the internal reader to submit a job.
12	3	`User not authorized to issue a CIM request`	CIM detected an authentication or authorization failure during the request. For the requested service to be performed, the user must be authorized to use the CIM server and be permitted to the JES2-JES3Jobs CIM provider. The requested service was one of the following: Hold a job Release a job Change the job class Cancel a job Delete a job. CIM provides jobs (CFZSEC and CFZRCUST) to help you configure the CIM server, including security authorizations and file system customization. See the chapter on CIM server quick setup and verification in z/OS Common Information Model User's Guide.

Category 7 — Unexpected error

Table 7 shows the possible conditions for this error category.

Table 7. Category 7 errors
rc	reason	message	Description
16	1	`Server error occurred`	For details about the exception, see the stack property of the JSON error report document, which is described in Error report document.

Category 8 — SSI extended status error

Table 8 shows the possible conditions for this error category.

Table 8. Category 8 errors
rc	reason	message	Description
`n`	`m`	varies	The rc and reason (n,m) are set from the extended status function call of the subsystem interface (SSI Function Code 80) return code and the subsystem options block (SSOB) return code, respectively. The details property of the JSON error report document contains a message with more information. See Error report document.

Category 9 — Common Information Model (CIM) error

Table 9 shows the possible conditions for this error category.

Table 9. Category 9 errors
rc	reason	message	Description
4	2	`Incorrect jobname: “%s”`	Prior to the CIM service call, the job name was found to be null or an empty string.
4	3	`Incorrect jobid: “%s”`	Prior to the CIM service call, the job ID was found to be null or an empty string.
4	4	`Incorrect JES type`	Prior to the CIM service call, an incorrect JES type (not JES2 or JES3) was detected.
4	5	`Incorrect job class: “%s”`	Prior to the CIM service call, the job class was found to be null or an empty string.
8	—	varies	CIM internal error. An error occurred during setup or invocation of the CIM service.
12	m	`Error returned from CIM job` `{Cancel\|Hold\|Release\|` `Request Property Change}service`	CIM response error. Reason (m) is the reason code returned from CIM. The “details” property of the JSON error report document contains the CIM response text, if any. See Error report document.
16	—	`CIM connection failure`	A connection exception was encountered while processing the requested service. This error can occur during periods of concurrent high usage of these interfaces. Usually, the reason for the failure is a simple connection refused due to overload of the server. The application should try the request again. The number of retry attempts needed depends on how much work is being requested of the server. The requested service was one of the following: Hold a job Release a job Change the job class Cancel a job Delete a job.

Category 10 — SSI job modify error

Table 10 shows the possible conditions for this error category.

Table 10. Category 10 errors
rc	reason	message	Description
`n`	`m`	varies	The rc and reason (n,m) are set from the job modify function call of the subsystem interface (SSI Function Code 85) return code and the subsystem options block (SSOB) return code, respectively. The “details” property of the JSON error report document contains a message with more information. See Error report document.