3.2.4 Higher-Layer Triggered Events

  • Article

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

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

  • Client Request to send a query to a TDS server on an already established TDS connection. The Client Request is a request for one of four types of queries to be sent: SQL Command, 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 thus client and server resources. If a client implementation of the TDS protocol supports the Cancel Request event, it MUST handle it as described in this specification.

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

When a TDS client receives a Connection Open Request from the upper layer in the "Initial State" state of a TDS connection, it performs the following actions:

  • If the TDS client implements the Connection Timer, it MUST start the Connection Timer if the connection timeout value is not infinite.

  • If there is upper-layer request MARS support, it MUST set the B_MARS byte in the PRELOGIN message to 0x01.

  • It MUST send a PRELOGIN message to the server by using the underlying transport protocol.

  • If the transport does not report an error, it MUST enter the "Sent Initial PRELOGIN Packet" state.

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

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

  • If the TDS client implements the Query Timer, it MUST start the Client Request Timer if the client request timeout value is not infinite.

  • If MARS is enabled, the client MUST keep track whether there is an outstanding active request. If this is the case, then the client MUST initiate a new SMP session, or else an existing SMP session MAY be used.

  • Send either SQL Command, Bulk Load, Transaction Manager Request, or a RPC message to the server. The message and its content MUST match the requested message from the Client Request. If MARS is enabled, the TDS message MUST be passed through to the SMP layer.

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

When a TDS 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 client implements the Cancel Timer, it MUST start the Cancel Timer if the Attention request timeout value is not infinite.

  • Send an Attention message to the server. This indicates to the server that the client intends to abort the currently executing request. If MARS is enabled, the Attention message MUST be passed through to the SMP layer.

  • Enter the "Sent Attention" state.