The
z/OS XML parser API services
provide a return and reason code to indicate the success or failure
of the parse process. The return code is a fullword value that indicates
the class of the return status, and takes on one of the following
values:
- Success
(XRC_SUCCESS)
- Warning (XRC_WARNING) - parsing is successful, but incomplete.
This is most often caused by the z/OS XML parser reaching the
end of either the input or the output buffer.
- Failure (XRC_FAILURE) - a terminating failure has occurred. The
return information passed back in the parameters, such as the numbers
of bytes left in the input and output buffers, are valid. The extended
diagnostic information may also contain additional problem determination
information that is of use.
- Not-well-formed (XRC_NOT_WELL_FORMED) - a terminating failure
has occurred because the input document is not well formed. As with
the failure case above, all return information passed back through
the parameters and extended diagnostic area is valid.
- Fatal (XRC_FATAL) - a terminating error has occurred. None of
the return information is valid.
- Not valid (XRC_NOT_VALID) - The document is not valid according
to the specified schema.
In addition to the return code describing the class of error,
the reason code provides more detail. The reason code is only valid
when the return code is not XRC_SUCCESS. When a service of the
z/OS XML parser API returns
XRC_SUCCESS, the reason code may have any random value.
The
reason code itself is a fullword value, but is made up of two halfwords.
The upper halfword is reserved for a module identifier that is used
by IBM® Service to isolate the
source of the problem, and the lower halfword indicates the reason
why the parse process was paused or terminated. When checking the
value of the reason code, the caller must be sure to AND the reason
code with the reason code mask (XRSN_REASON_MASK) before testing the
value. The declaration of XRSN_REASON_MASK and all of the defined
reason code values are contained in the GXLYXR macro. A list of the
reason codes and their descriptions can be found in Reason codes listed by value.