The data retrieval response document has a format similar to the data load response document—as explained in Load Request Document Format—but it is easier to parse. The general format of a retrieval response document looks as follows:
- <rowsets> tag: This is the root element of a retrieval response document. Its children are:
- <rowset> tag: One <rowset> tag for each <free-query> tag sent in the request
- <error> tag
- <rowset> tag: Each <rowset> tag gets the same ID as the <free-query> tag in the retrieval request document to indicate to which query this rowset replies.
- <error> tag: This tag contains a complete description of the error. It is a required tag indicating whether a problem has occurred on rowset level. Errors on rowset level mostly point out problems in the RDBMS.
<rowsets> tag
Root element of a retrieval response document.
The <rowsets-tag> tag can have the following children, which are described in the following sections:
<rowset> Tag
Holds the information for a specific rowset.
Each <rowset> tag gets the same ID as the <free-query> tag in the retrieval request document to indicate to which query this rowset replies.
| Attribute | Definition |
|---|---|
| id | Required. Holds the same ID value as the <free-query> tag in the retrieval request document to help identify to which query this rowset replies. |
The <rowset> tag can have the following children, which are described in the following sections:
<row> Tag
Holds the value for a specific row.
| Attribute | Definition |
|---|---|
| rownum | Required. Holds the ordinal number of the row. |
The <row> tag can have the following children, which are described in the following sections:
<column name> tag
Holds the actual name of the column or its alias (as it is retrieved from the RDBMS), depending on the query.
| Attribute | Definition |
|---|---|
| type | Optional. Holds the Java representation of the column type, such as STRING, INTEGER, FLOAT, DOUBLE. If the retrieval request contains the type attribute, each column of the response request consequently contains a type attribute, too. |
<rowset-info> tag
Holds metadata on the query, such as the number of rows affected.
| Child | Definition |
|---|---|
| <affected-rows> | Optional. Indicates how many rows have been affected:
|
| <more-rows> | Optional. Indicates if more rows are to be retrieved. Can have the values TRUE or FALSE. For example, if the <meta-data> tag of the <free-query> tag requests only five rows and the query returns 10 rows, the value of the <affected-rows> tag is five and the <more-rows> tag is TRUE. |
<error> tag
Holds information if an error has occurred. Upon successful connection, this tag has a value of zero. Any other value indicates an error.
| Child | Definition |
|---|---|
| <code> | Required. Contains an integer value of the retrieve results. A value of 0 indicates a successful, error-free completion. Any other value indicates an error. |
| <description> | Optional. If an error occurs, this tag contains the error description. |
| <external-code> | Optional. If an RDBMS error occurs, this tag contains the RDBMS code. |
| <external-description> | Optional. If an RDBMS error occurs, this tag contains the RDBSM error description. |