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 that are produced or detected by the Java/ JNI/ C/ HLASM/ VSAM layer.	Category 3 — VSAM API error
VSAM system	4	Errors that are produced or detected by VSAM. The return code and reason code are VSAM-specific.	Category 4 — VSAM system error
VSAM ABEND	5	ABEND information that results from VSAM failures.	Category 5 — VSAM ABEND error
Service	6	Errors that are 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 that are 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 that are produced or detected by the Common Information Model (CIM) interface.	Category 9 — Common Information Model (CIM) error
SSI job modify	10	Errors that are 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
Return code (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 information 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 information code from the dynamic allocation request (field S99INFO in the input request block S99RB). For information about dynamic allocation and its related error and information codes, see Dynamic allocation in 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 its related return codes, see BPXWDYN: A text interface to dynamic allocation and dynamic output in 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 to cancel the job and purge its output. 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 information 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 information 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 information code, see Dynamic allocation in 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
Return code (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 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
Return code (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
Return code (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
Return code (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 modification requests must have a content type of `application/json`.
4	4	`Value of %s query parameter is not valid`	The query parameter that was 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'`	In the job modification request, the "request" property is set to an incorrect value. The required value is "cancel."
4	6	`Request does not contain a valid job update request`	In the job modification request, the 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 path information (`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 send the request 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 modification request specifies 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 by 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`	On a job submission request, the Content-Type request header specified an unsupported character set (`charset`).
4	15	`DD names are not supported for submit input`	The `filename` property in the JSON document started with `//DD:`, indicating the `dd:ddname` syntax. This syntax is not supported.
4	16	`Data set not found`	The data set specified in the JSON document that was provided on the submit job interface was not found. Possibly, the data set is not cataloged.
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 that names 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 a job is submitted from a data set.
4	20	`Service not implemented: %s`	The requested service is not supported. 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 a job is submitted 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 a job is submitted from a data set.
4	24	`Content type '%s' not valid for internal reader mode '%s'`	The values that are 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 that is 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 was made to define more than 128 symbols, which is not allowed.
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 that is identified in the message is not supported by the primary job entry subsystem.
4	32	`Error parsing JSON input`	On a job submission request, the header Content-Type specified `application/json`. However, an exception occurred when the input JSON document was processed. 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. For details about the exception, check the z/OSMF logs.
4	33	`Data set is migrated: %s`	The JSON document specifies a z/OS data set that was migrated. No recall was issued. No job was submitted.
4	34	`Recall issued for migrated data set: %s`	The JSON document specifies a z/OS data set that was migrated. A recall without waiting was issued. No job was submitted.
4	35	`Error recalling data set, RC=%d`	An error occurred during the recall of a migrated data set. The return code from the ARCHRCAL service is included in the message. For information about the ARCHRCAL service and return codes from the DFSMShsm user macros, see ARCHRCAL: Recalling a data set in z/OS DFSMShsm Managing Your Own Data.
4	36	`Incorrect internal reader class: %s. Must be one character in length.`	The 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.`	In the job modification request, the "version" property or the X-IBM-Job-Modify-Version request header is set to an incorrect value. The valid values are `"1.0"` or `"2.0"`.
4	38	`The query parameters search and research cannot be used together.`	The search and research query parameters are mutually exclusive; they cannot be used together. Specify either search or research, but not both.
4	39	`The query parameters search and research are allowed only on mode=text requests.`	The query parameters search and research cannot be used when mode is set to a value other than text, such as `mode=record` or `mode=binary`.
4	40	`The query parameter maxreturnsize is not a valid integer.`	The query parameter maxreturnsize must be set to a valid integer value, for example,`maxreturnsize=100`.
8	1	`Unable to query information about submitted job: %s`	The job status for the submitted job was not 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 the end of file (EOF) was reached.
8	3	`Range start is beyond end of spool file %d for job %s`	In a GET request for 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`	In a GET request for a range of records in a spool file, the X-IBM-Record-Range header specified a record start value that was greater than 2**31-1.
8	5	`Error opening input data set: %s`	An error occurred opening the input z/OS data set. For a message with additional information, check the z/OSMF logs.
8	6	`Error reading submit input data`	An error occurred reading the submit input data. For a message with additional information, check the z/OSMF logs.
8	7	`Error opening input file: %s`	An error occurred opening the input z/OS UNIX file. For a message with additional information, check the z/OSMF logs.
8	8	`IAZSYMBL error defining %s`	The JES symbol definition service (IAZSYMBL) failed during the attempt 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, check the z/OSMF logs.
12	1	`Not authorized to access spool file`	An authorization check failed during the attempt to open the requested spool file.
12	2	`Not authorized to submit job`	An authorization check failed during the attempt 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. To use the requested service, 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. For more information, see Quick guide: CIM server 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
Return code (rc)	Reason	Message	Description
16	1	`Server error occurred`	For details about the exception, check the z/OSMF logs.

Category 8 — SSI extended status error

Table 8 shows the possible conditions for this error category.

Table 8. Category 8 errors
Return code (rc)	Reason	Message	Description
`n`	`m`	Varies	The return and reason codes (n,m) are set from the extended status function of subsystem interface (SSI) Function Code 80 return code and the subsystem options block (SSOB) return code. 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
Return code (rc)	Reason	Message	Description
4	2	`Incorrect jobname: "%s"`	Before the CIM service call, the job name was found to be null or an empty string.
4	3	`Incorrect jobid: "%s"`	Before the CIM service call, the job ID was found to be null or an empty string.
4	4	`Incorrect JES type`	Before the CIM service call, an incorrect JES type (not JES2 or JES3) was detected.
4	5	`Incorrect job class: "%s"`	Before 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 that was 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 when the request was processed. This error can occur during periods of concurrent high usage of the REST interfaces. Usually, the reason for the failure is a connection refused due to overload of the server. The application can try the request again. The number of retry attempts that are needed depends on how much work is being requested of the server. One of the following services was requested: 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
Return code (rc)	Reason	Message	Description
`n`	`m`	Varies	The return and reason codes (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. The "details" property of the JSON error report document contains a message with more information. See Error report document.