3.2.4 Higher-Layer Triggered Events

  • Article

A TDS 4.2 client MUST support the following events from the upper layer:

  • Connection Open Request to establish a new TDS 4.2 connection to a TDS 4.2 server.

  • Client Request to send a request to a TDS 4.2 server on an already established TDS 4.2 connection. The Client Request is a message of one of the following four types: SQL Batch, Bulk Load, transaction manager request, or an RPC.

In addition, it SHOULD support the following event from the upper layer:

  • Cancel Request to cancel a client request while waiting for a server response. For example, this enables the upper layer to cancel a long-running client request if the user/upper layer is no longer seeking the result, thus freeing up client and server resources. If a client implementation of the TDS 4.2 protocol supports the Cancel Request event, it MUST handle it as described in this specification.

The processing and actions triggered by these events are described in the remaining parts of this section.

When a TDS 4.2 client receives a Connection Open Request from the upper layer in the initial state of a TDS 4.2 connection, it MUST perform the following actions:

  • If the TDS 4.2 client implements the Connection Timer, it MUST start the Connection Timer if the connection time-out value is not infinite.

  • Send a Pre-Login message to the server, by using the underlying transport protocol.

  • If the transport does not report an error, then enter the Sent Initial Pre-Login Message state.

When a TDS 4.2 client receives a Connection Open Request from the upper layer in any state other than the initial state of a TDS 4.2 connection, it MUST indicate an error to the upper layer.

When a TDS 4.2 client receives a Client Request from the upper layer in the Logged In state it MUST perform the following actions:

  • If the TDS 4.2 client implements the Client Request Timer, it MUST start the Client Request Timer if the client request time-out value is not infinite.

  • Send either the SQL Batch, Bulk Load, transaction manager request, or RPC message to the server. The message and its content MUST match the requested message from the Client Request.

  • If the transport does not report an error, then enter the Sent Client Request state.

When a TDS 4.2 client supporting the Cancel Request receives a Cancel Request from the upper layer in the Sent Client Request state, it MUST perform the following actions:

  • If the TDS 4.2 client implements the Cancel Timer, it MUST start the Cancel Timer if the Attention request time-out value is not infinite.

  • Send an Attention message to the server. This indicates to the server that the currently executing request SHOULD be aborted.

  • Enter the Sent Attention state.