Deprecated - This page is no longer relevant

Result Formats

Result Formats

RdbHost delivers the results of a query as an XML, JSON or binary page; the structure of the XML result page is described here.

The error codes themselves are documented on their own page.

For most applications, JSON is the most straight-forward and easiest format to use. JSON docs can be found here. If you need your data raw and can forgo any structure to the data, see documentation on the binary format here.

XML

The root element of an RdbHost result will always be called 'xml' (as the outermost container), and will always have a 'status' subelement. The evaluation of the result set should always start with inspecting the value of the status element. Other elements may, or may not, be present, depending on the result status.

<xml xmlns="http://rdbhost.com/xml.html"> <status value="error">ProgrammingError</status> ... </xml>

The 'status' element will have an attribute 'value' whose value is one of 'error', 'complete', 'incomplete', or 'deferred'. The body of the tag is 'OK' for successful results, and an error class name for errors.

When 'status' is 'error', there will be an 'error' element, a sibling of 'status'.

<xml xmlns="http://rdbhost.com/xml.html"> <status value="error">ProgrammingError</status> <error code="-">ERROR Message</error> </xml>

The attribute 'value' will be an error code, and the body will be an error message; both of these are usually from an underlying component, such as PostgreSQL or SimpleJSON.

When the result is successful (not error), the remaining data elements will depend on whether the query was one statement, or more than one. Multiple SQL statements can be included in the query string, seperated by ';' characters.

Single Statement

First, we will consider the case of a single statement.

When the result is successful (not error), either complete or incomplete, there will be a 'row_count' element like:

<xml xmlns="http://rdbhost.com/xml.html"> <status value="complete">OK</status> <row_count value="1">1 Rows Affected</row_count> ... </xml>

row_count will have an attribute 'value', with a number, and the body will be a string. The row_count number value might be -1, or might be the number of records updated, inserted or returned from a SELECT. The row_count value for a SELECT will generally not be more than 101, even if more qualifying records are in the database, simply because the server stops fetching at 101.

Results from a SELECT query will include a 'records' element, and that 'records' element will always include a 'header' element and a 'rows' element:

<xml xmlns="http://rdbhost.com/xml.html"> <status value="complete">OK</status> <row_count value="1">1 Rows Affected</row_count> <records> <header> <fld type="21">a</fld> </header> <rec> <fld>2</fld> </rec> </records> </xml>

The 'header' element contains one item (a container element) for each field in the selection set. Each such field element in the header has a 'value' attribute, containing PostgreSQL's field-type-code, and the body will be the name of the field.

The 'rows' element may be empty, depending on whether the query returned any rows. If it has data, it will contain one or more records; each record is a container element containing an element for each field value. Each field element will have the field value as the element body. It is up to the user to convert the body text to an appropriate JavaScript or Python value. If the field is null, the element will have a 'null' attribute, and the body will be empty.
Request this format with the parameter 'format=xml' (lower case).

Multiple Statements

The case of multiple statements in the query is similar, except that instead of having row_count and records elements as peers of status, the data object has one element 'result_sets', which is a container with one element for each statement. Each such element is a 'result_set' container containing its own status tag, and conditionally row_count tag and records container elements, as described above. The status values within result_sets containers will always be <status value="complete"/*> or <status value="incomplete"/>, as any error results in a single error status and no result_sets.

<xml> <status value="complete">OK</status> <result_sets> <result_set> <row_count value="0">0 Rows Affected</row_count> <status value="complete"/> </result_set> <result_set> <row_count value="1">1 Rows Affected</row_count> <status value="complete"/> <records> <header> <fld type="23">?column?</fld> </header> <rec> <fld>3</fld> </rec> </records> </result_set> </result_sets> </xml>

XML-Easy

XML-Easy format is like XML, described above, except for how the fields are described. The data converts from xml using the same XML parsers. The 'records' element, though, contains no header, and each field element contains two attributes; the 'type' attribute holds a PostgreSQL field-type-code, and the 'name' attribute holds the field name.

<xml xmlns="http://rdbhost.com/xml.html"> <status value="complete">OK</status> <row_count value="1">1 Rows Affected</row_count> <records> <rec> <fld name="a" type="21">2</fld> <fld name="b" type="21">1</fld> </rec> </records> </xml>

The name XML-Easy suggests the data are easier to use, as each record element contains the field values, names and types, altogether.
Request this format with the parameter 'format=xml-easy' (lower case).