QDoc Specifications and Standards > QDoc XML Elements > Common Response Data
  
Common Response Data
As part of every outbound QDoc response, QDocs report the outcome of a request along with any exception conditions. Because of its inherent commonality, a single set of XML elements is specified for all QAD products.Common response data in QDocs is handled differently depending on the version of the QDoc syntax specification in use.
QDoc Specification 1.1
One required element, result, is included in all QDoc response documents as a single-level child under the root. This is a QAD-defined element used to contain the result.The dsExceptions element occurs exactly once in response QDocs, and contains a variable number of temp_err_msg elements, which in turn contain the tt_msg_* fields. The exception node used in the QDoc syntax version 1.0 translates to the temp_err_msg node.Each temp_err_msg includes the following elements:
• tt_msg_nbr: identifies the type of exception (required)
• tt_msg_desc: briefly describes the exception condition (required)
• tt_msg_sev: designates the severity of the exception—informational, warning, error (optional, default error)
• tt_msg_field: identifies the specific field in the request for which the exception was raised (optional, no default)
• tt_msg_context: identifies the context within the request, typically an element or row instance, in which the exception was raised (optional, no default)
• tt_msg_data: contains free-form trace information about the exception; this temp-table is also used inside QAD Enterprise Applications
Note: OpenEdge errors trapped by the Service Interface are stored in this table along with application exceptions. OpenEdge errors can be identified by the OE- prefix prepended to the message number in the tt_msg_nbr field.
• tt_msg_keys: identifies application key values identifying the row associated with the exception
• tt_msg_datetime: identifies the date and time when the exception was raised
• tt_msg_processed: identifies whether or not the exception has been handled
• tt_level: identifies the level of the program stack in which the exception occurred
• tt_msg_index: identifies the unique sequential key within the table
QDoc Specification 1.0
Two required elements are included in all QDoc response documents as single-level children under the root:
• result, a SOAP-standard element defined in the namespace
http://www.w3.org/2002/12/soap-rpc
• returnValue, a QAD-defined element returning the value success, warning, or error
This is pessimistic rather than optimistic usage. In the case of a multi-part QDoc (for example, a maintainSalesOrder request that includes two sales orders), the returnValue element is set to error if any of the lines in either sales order fail for any reason.The result element always has the value returnValue, as its only purpose within the SOAP 1.0 standard is to reference the element within the SOAP response that contains the return value of the QDoc. This indirect approach permits the standard result element to be completely defined within the soap-rpc namespace, while still permitting the application to return its own strongly typed value.
Zero or more exception elements are included in all QDoc response documents as single-level children under the root. Each exception includes the following elements of the type string:
• number: identifies the type of exception (required)
• description: briefly describes the exception condition (required)
• severity: designates the severity of the exception
• field: identifies the specific field in the request for which the exception was raised (optional, no default)
• context: identifies the context within the request, typically an element or row instance, in which the exception was raised (optional, no default)
• trace: a detailed trace of the method execution that raised the exception, typically a Java stack trace (optional, no default)
It is possible for a QDoc response to contain nothing inside the QDoc root element except one or more exception elements plus the result and returnValue elements. This would be the case for errors recognized before application processing of the QDoc has begun; for example, if the QDoc request’s name-version is not supported or its XML content is not well formed.A common ExceptionType for the exception element is defined and stored in the QDoc namespace and common XML schema files. See QDoc Namespaces. Its XML schema definition is shown in the following code sample.
<complexType name="ExceptionType">
<annotation>
<documentation>
An exception message returned from a QDoc request by
the QAD application.
</documentation>
</annotation>
<sequence>
<!-- number and description fields are required -->
<element name="number" type="string"/>
<element name="description" type="string"/>
<element name="severity" minOccurs="0"
default="error">
<simpleType>
<restriction base="string">
<enumeration value="informational"/>
<enumeration value="warning"/>
<enumeration value="error"/>
</restriction>
</simpleType>
</element>
<element name="field" type="string" minOccurs="0"/>
<element name="context" type="string" minOccurs="0"/>
<element name="trace" type="string" minOccurs="0"/>
</sequence>
</complexType>
A common ReturnValueType for the returnValue element is also defined and stored in the QDoc namespace and common XML schema files. Its XML schema definition is shown in the following code.
<simpleType name="ReturnValueType">
<annotation>
<documentation>
The value returned by the QAD application.
</documentation>
</annotation>
<restriction base="string">
<enumeration value="success"/>
<enumeration value="warning"/>
<enumeration value="error"/>
</restriction>
</simpleType>