3.4 Query Execution

Queries are executed via different subprotocols depending on the type of the query and the query length. There are three types of queries: query, update, bulk load.

If the query is not longer than the message body (10240 bytes) the client sends the Execute message that contains a query statement to the server. If the query is longer than the message body the client must send the query in parts: each part is in the body of se_ExecuteLong message. After all parts of the query are sent, client must send se_LongQueryEnd message (with the empty body), thus to make the server understand that the whole query is sent.

The server analyzes the query text to identify the type of the query and runs the corresponding subprotocol. The following sections describe these subprotocols.

3.4.1 Querying Data

The client sends a query in the se_Execute message, or in the se_ExecuteLong messages plus the se_LongQueryEnd message. The first byte of the query text is a format of the result to obtain - SXML [1] or XML. Use 0 if you want to get the result of the query in XML, 1 - to get the result in SXML.

The server processes the query. If the query succeeds the server sends the se_QuerySucceeded message to the client and then sends a number of messages that contain the first item of the result sequence and query debug information (if any) to the client in the way described below.

When the client needs to get the next item of the result sequence it sends the se_GetNextItem message. The server then sends the next item of the result sequence.

The way server sends items depends on the protocol version:

Protocol Versions 1.0, 2.0, 3.0: Server may send every item in parts. Every part of the item is enveloped in the se_ItemPart message. When the whole item is sent, the server sends the se_ItemEnd message or se_ResultEnd message if it was the last item.

Protocol Version 4.0: Server sends items in the following way. se_ItemStart message is sent in the first place. It contains type and content of the item being sent. If content is too long to be sent within one message, server may send it in parts. Every part of the item is enveloped in the se_ItemPart message. When the whole item is sent, the server sends the se_ItemEnd message or se_ResultEnd message if it was the last item.

When the result sequence has ended, server on receiving se_GetNextItem from client sends the ResultEnd message without prior sending the se_ItemPart message.

While sending result data server may also send any number of messages se_DebugInfo containing debug information if there is any.

Client is not required to get all the items of the result sequence. It can send next query for execution before all the items of the result sequence are received from the server.

If the query failed, the server sends message se_QueryFailed to the client.

The possible instructions from the client in this phase are:

• se_Execute. The body contains an XQuery query text.
• se_ExecuteLong. The body contains a part of a long XQuery query.
• se_LongQueryEnd. Does not contain a body.
• se_GetNextItem. Does not contain a body.

The possible instructions from the server in this phase are:

• se_QuerySucceeded. Does not contain a body.
• se_QueryFailed. The body contains the error code and error info.
• se_DebugInfo. The body contains the debug type and debug info. (Since version 2.0)
• se_ItemStart. The body contains type of the item being sent and the part of the item. (Since version 4.0)
• se_ItemPart. The body contains the part of the item.
• se_ItemEnd. Does not contain a body.
• se_ErrorResponse. Body contains info.

3.4.2 Updating Data

The client sends the se_Execute message (or the se_ExecuteLong messages plus the se_LongQueryEnd message) that contains an update statement. The server processes the update. If the update succeeded the server sends the se_UpdateSucceeded message to the client. If the update failed, the server sends the se_UpdateFailed message.

Before sending se_UpdateSucceeded or se_UpdateFailed message sever may send any number of se_DebugInfo messages if there is any debug information.

The possible instructions from the client in this phase are:

• se_Execute. The body contains an update statement.
• se_ExecuteLong. The body contains a part of a long XQuery query.
• se_LongQueryEnd. Does not contain a body.

The possible instructions from the server in this phase are:

• se_UpdateSucceeded. Does not contain a body.
• se_UpdateFailed. The body contains the error code and error info.
• se_DebugInfo. The body contains the debug type and debug info.
• se_ErrorResponse. Body contains info.

3.4.3 Bulk Load

The client sends the se_Execute message that contains a bulk load statement. The server picks out the name of the file and sends the se_BulkLoadFileName message that contains the name.

Since version 2.0 of the Sedna Client-Server protocol server can send multiple se_BulkLoadFileName messages if there were multiple file names in a query. This currently can happen in LOAD MODULE statement.

The client reads the file specified. If there is no such file or some access errors occur, the client sends se_BulkLoadError message to the server. Else the client transfers the data from the file to the server by portions. Each portion is sent in the se_BulkLoadPortion message.

When the whole file is sent, the client sends the se_BulkLoadEnd message. The server answers with the se_BulkLoadSucceeded or se_BulkLoadFailed message.

The possible instructions from the client in this phase are:

• se_Execute. The body contains a query for bulk load.
• se_BulkLoadError. Does not contain the body.
• se_BulkLoadPortion. The body contains portion of data.
• se_BulkLoadEnd. Does not contain the body.

The possible instructions from the server in this phase are:

• se_BulkLoadFileName. The body contains file name.
• se_BulkLoadSucceeded. Does not contain the body.
• se_BulkLoadFailed. The body contains the error code and error info.
• se_ErrorResponse. Body contains info.