Open Client Client-Library/C Reference Manual

Home

Open Client Client-Library/C Reference Manual

Chapter 2: Topics

Capabilities

Capabilities describe features that a client/server connection supports.

For a list of capabilities, see "ct_capability" .

What are Capabilities Good For?

An application can use capabilities to find out what features are supported by a connection's actual TDS version.

In particular, an application can:

Find out whether a server connection supports a particular type of request.
Tell a server not to send a particular type of response on a connection.

Types of Capabilities

There are two types of capabilities:

CS_CAP_REQUEST capabilities, or "request capabilities," which describe the types of client requests that can be sent on a server connection.
CS_CAP_RESPONSE capabilities, or "response capabilities," which describe the types of server responses that a connection does not wish to receive.

Setting and Retrieving Capabilities

Before calling ct_connect to open a connection, an application can:

Retrieve request or response capabilities, to determine what request and response features are normally supported at the connection's current TDS version level. A connection's TDS level defaults to the version level that the application requested in its call to ct_init . An application can change a connection's TDS level by calling ct_con_props with property as CS_TDS_VERSION.
Set response capabilities, to indicate that a connection does not wish to receive particular types of responses. For example, an application can set a connection's TDS_RES_NOEED capability to CS_TRUE to indicate that the connection does not wish to receive extended error data.

During the connection process, the client and server negotiate a TDS version level for the connection. The TDS version level determines which capabilities the connection will support.

After a connection is open, an application can:

Retrieve request capabilities to find out what types of requests the connection will support.
Retrieve response capabilities to find out whether the server has agreed to withhold the previously-indicated response types from the connection.

Setting and Retrieving Multiple Capabilities

Gateway applications often need to set or retrieve all capabilities of a type category with a single call to ct_capability. To do this, an application calls ct_capability with:

type as the type category of interest
capability as CS_ALL_CAPS
value as a CS_CAP_TYPE structure

Client-Library provides the following macros to enable an application to set, clear, and test bits in a CS_CAP_TYPE structure:

CS_SET_CAPMASK(mask, capability)
CS_CLR_CAPMASK(mask, capability)
CS_TST_CAPMASK(mask, capability)

where mask is a pointer to a CS_CAP_TYPE structure and capability is the capability of interest.


	Expand Search