Error reporting categories
This section describes the error categories and associated error codes that can be returned in the JSON error report document for z/OS data set and file REST interface requests. This document is described in Error report document.
Categories
Table 1 shows
the error categories that are defined for errors returned in z/OS data set and file REST interface operations.
| Category | Ordinal Value | Description | Where the error details are described |
|---|---|---|---|
| Service | 1 | Errors produced or detected in the service layer. | Category 1 — Service error |
| Message queue | 2 | Errors produced or detected by the message queue. | Category 2 — Message queue error |
| CEA | 3 | Errors produced or detected by the common event adapter (CEA) interface. | Category 3 — Common event adapter (CEA) error |
| ISPF | 4 | Errors produced or detected by the Interactive System Productivity Facility (ISPF) interface. | Category 4 — ISPF error |
| CSI | 5 | Errors produced or detected by the catalog search interface (CSI). | Category 5 — Catalog Search Interface (CSI) error |
| Read or write function | 6 | Errors returned from an attempted read or write request. | Category 6 — Read or write error |
| JSON | 7 | Errors produced or detected when parsing JSON. | Category 7 - JSON Parser Conditions |
| XL C/C++ | 8 | Errors produced or detected by z/OS XL C/C++ | Category 8 - z/OS XL C/C++ Conditions |
| Unexpected | 16 | Unexpected errors detected. | Category 16 — Unexpected error |
Category 1 — Service error
Table 2 shows the possible conditions for this error category.
| rc | reason | message | Description |
|---|---|---|---|
| 4 | 1 | %s |
The request specified a URL that is not valid. %s indicates which parts of the URL are invalid, such as path information, data set name and volume serial. |
| 4 | 2 | Invalid data set name length. |
The request specified a data set name length that is not valid. Note that data set names cannot exceed 44 characters in length. |
| 4 | 3 | The specific data set name is
invalid. |
The request specified a data set name (dslevel) that is not valid. |
| 4 | 4 | Retrieving USS files should start with absolute
path. |
The requested file cannot be retrieved because the request is missing an absolute path name, which is required. When retrieving UNIX files, the file path must be an absolute (or fully-qualified) path name, rather than a relative (or partially-qualified) path name. |
| 4 | 5 | Length of USS path is invalid. |
The request specified a UNIX file path length that is not valid. |
| 4 | 6 | The specific path is invalid. |
The request specified a UNIX file path that is not valid. |
| 4 | 7 | The specific volser is invalid. |
The request specified a volume serial (volser) that is not valid. |
| 4 | 8 | File not found. |
The request specified a file that does not exist. |
| 4 | 9 | Incorrect content type. |
The request specified an unsupported content type. |
| 4 | 10 | Unrecognized HTTP method.
|
The request is not recognized as a supported HTTP method. |
| 4 | 11 | POST method is not supported. |
The POST method was specified, however POST is not a supported HTTP method. |
| 4 | 12 | Incorrect attribute was specified. |
The request contained one or more attributes that are not valid. |
| 4 | 13 | Incorrect parameter was specified. |
The request contained one or more parameters that are not valid. |
| 4 | 14 | The specific JSON data in the request is invalid. |
JSON data in the request is invalid. |
| 4 | 15 | The size of the data to be written is invalid. |
The size of the data to be written is invalid. |
| 4 | 16 | Request content-length must be specified. Request content-length
was too long. Request content was longer than specified content-length. |
Only used in ValidateJsonServlet.C. |
| 4 | 17 | Request document contained invalid JSON. |
Not currently used. |
| 4 | 18 | Member name is not valid. |
Member name is not valid. |
| 4 | 19 | Unix file/directory exists. |
Unix file/directory already exists. |
| 8 | 1 | Unable to get JSON Response. |
Not currently used. |
| 8 | 2 | Unable to get JSON Response Table. |
Not currently used. |
| 8 | 3 | Unable to load ISPEXEC. |
The ISPF service route ISPEXEC could not be loaded. |
| 8 | 4 | Unable to load TSO servlet mappings. |
The servlet dispatcher was not able to load the servlet mappings JSON file. |
| 8 | 5 | A servlet-mapping was not found for servlet-path. |
A servlet mapping matching the request could not be found. Indicates a servlet-mapping configuration error. |
| 8 | 6 | ExceptionServlet threw an exception after commit. Servlet failed
but could not send error response. |
An exception was thrown by the servlet. |
| 8 | 7 | TsoServlet already committed. |
An exception was thrown by the servlet after its output stream header was committed. |
Category 2 — Message queue error
Table 3 shows the possible conditions for this error category.
| rc | reason | message | Description |
|---|---|---|---|
| 12 | 1 | The message
queue cannot be created. |
The message queue cannot be created. |
| 4 | 1 | Timeout |
A timeout occurred when receiving a message from the message queue. MSG_QUEUE_PROTOCOL_ERROR_TIMEOUT |
| 4 | 2 | Received unexpected msgType=nn |
Received unexpected message. MSG_QUEUE_PROTOCOL_ERROR_UNEXPECTED |
| 4 | 3 | ServletDispatcher failed. |
Back-end ServletDispatcher failed with the reason <reason>, for example,
TSO Prompt was received when TsoServletResponse was expected. MSG_QUEUE_PROTOCOL_ERROR_ENDED |
| 4 | 4 | Queue full while sending. |
Message queue is full while sending the specific <message type>. MSG_QUEUE_PROTOCOL_ERROR_FULL |
| 4 | 5 | Illegal state. |
The message queue is in an illegal state. MSG_QUEUE_PROTOCOL_ERROR_ILLEGAL_STATE |
| 5 | 1 | Error parsing TsoServletResponse. |
Error occurred when paring TsoServletResponse. MSG_QUEUE_JSON_PARSE_ERROR |
| 5 | 2 | Error serializing TsoServletRequest. |
Error occurred when serializing TsoServletRequest. MSG_QUEUE_JSON_SERIALIZE_ERROR |
| 12 | 1 | The Message queue cannot be created. |
The message queue cannot be created. |
| 12 | 2 | Not used currently. | |
| 12 | 3 | Message queue size is less than minimum. |
Message queue size is less then the required minimum size. MSG_QUEUE_ERROR_SIZE_ERROR |
| 12 | 4 | Message prefix bytes are too short. |
Message prefix bytes are shorter than expected. MSG_QUEUE_ERROR_DECODING |
| 16 | n(errno) | Varies. |
This is an error from msgsnd()/msgrcv()/etc. The errno will be used as the
reason. MSG_QUEUE_SYS_ERROR |
Category 3 — Common event adapter (CEA) error
Table 4 shows the possible conditions for this error category.
| rc | reason | message | Description |
|---|---|---|---|
| 12 | 1 | TSO launcher
exception: Client is not authorized for instrumentation. |
The requestor lacks sufficient authority to access the requested common event adapter (CEA) service. |
| 12 | 2 | TSO launcher
exception: Error occurred. |
The requested CEA service encountered an error. |
| 12 | 3 | TSO launcher
exception: CEA address space is not available. |
The CEA address space is not active or is not available. |
| 12 | 4 | TSO launcher
exception: TSO address space cannot be created. |
The TSO/E address space cannot be created because a required system resource is not available. |
| 12 | 5 | CeaTsoEnd request failed. |
An error occurred ending a TSO Address Space. CEA TSO Reason code = 4103. CEA_ERROR_END_TSO_FAILED |
| 12 | 6 | Not currently used. CEA_ERROR_CMD_NOT_FOUND |
|
| 12 | 7 | Unable to find the system you requested | CEA_ERROR_NO_TARGET_SYSTEM |
| 12 | n | Error occurs while using remote CEA TSO address space services | Refer to CEA TSO address space services reason code and diagnostic code for details. |
Category 4 — ISPF error
Table 5 shows the possible conditions for this error category.
| rc | reason | message | Description |
|---|---|---|---|
| n | m | varies | The return and reason code values match the return and reason code values that are set by the ISPF service. |
Category 5 — Catalog Search Interface (CSI) error
Table 6 shows the possible conditions for this error category.
| rc | reason | message | Description |
|---|---|---|---|
| n | m | varies | The return and reason code values match the return and reason code values that are set by the consolidated software inventory (CSI) service. |
Category 6 — Read or write error
Table 7 shows the return and reason codes that can be set for a read or write request.
| rc | reason (hex) | message | Description |
|---|---|---|---|
| 8 | 201 |
<methodName> failed |
Unable to open a data set or member,
<methodName> like fopen() or freopen() failed.RW_ERROR_OPEN_FAILED |
| 8 | 202 |
<methodName> failed |
Unable to close a data set or
member,<methodName> like fclose() failed. If occurs for a write/put operation,
the data set contents are not predictable.failedRW_ERROR_CLOSE_FAILED |
| 8 | 204 |
Client ETag does not match the current ETag for the data
set. |
The attempt to write to the data set failed because the supplied ETag does not
match the current ETag of the requested data set. This mismatch indicates that the data set content
was modified in the time since the caller obtained the ETag. RW_ERROR_DS_ETAG_NOT_MATCHED |
| 8 | 208 |
.<methodName> error |
An error, <methodName> like
fread(), occurred during I/O to a data set or Unix file.RW_ERROR_IO |
| 8 | 20C |
Member not found. |
The member cannot be located in the partitioned data set. Perhaps the data set
name or member name was incorrectly specified. RW_ERROR_MBR_NOT_FOUND |
| 8 | 0000020A |
Dynamic allocation failed. |
This RC is combined with S99ERROR in the high halfword. RW_ERROR_DS_DYNALLOC_ERR |
| 8 | 1708020A |
ISPF LMINIT - data set
not found. |
The specified data set cannot be found. Perhaps the data set name or member
name was incorrectly specified. RW_ERROR_DS_NOT_FOUND |
| 8 | varies |
Varies. |
For UNIX file I/O errors, the reason code consists of the errno in the high order 16 bits and the errno2 in the low order 16 bits. |
| 8 | 5E30062 |
File not found. |
The specified UNIX file cannot be found. Perhaps the data set name or member
name was incorrectly specified. RW_ERROR_FS_NOT_FOUND |
| 8 | 5B6F0002 |
Client is not authorized for file access. |
The request for the UNIX file failed because the caller does not have
sufficient authority to access the file. RW_ERROR_FS_AUTH |
| 8 | 406 |
Client ETag does not match the current ETag for the
file. |
The attempt to write to the UNIX file failed because the supplied ETag does
not match the current ETag of the requested file. This mismatch indicates that the file content was
modified in the time since the caller obtained the ETag. RW_ERROR_FS_ETAG_NOT_MATCHED |
Category 7 - JSON Parser Conditions
Category 7 JSON parser conditions shows the possible conditions for this error category.
| rc | reason | message | Description |
|---|---|---|---|
| n | m | Varies. |
The rc and reason are set from the low level JSON Parser return code and reason code. |
Category 8 - z/OS XL C/C++ Conditions
Category 8 z/OS XL C/C++ Conditions shows the possible conditions for this error category.
| rc | reason | message | Description |
|---|---|---|---|
| n | m | Varies. |
The rc and reason are set from the low level z/OS XL C/C++ return code and reason code. |
Category 16 — Unexpected error
Table 10 shows the possible conditions for this error category.
| 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. |