Set or retrieve a client/server capability.
CS_RETCODE ct_capability(connection, action, type, capability, value) CS_CONNECTION *connection; CS_INT action; CS_INT type; CS_INT capability; CS_VOID *value;
A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/server connection.
One of the following symbolic values:
Value of action |
Meaning |
|---|---|
CS_SET |
Sets a capability |
CS_GET |
Retrieves a capability |
The type category of the capability. The following table lists the symbolic values for type:
Value of type |
Meaning |
|---|---|
CS_CAP_REQUEST |
Request capabilities. These capabilities describe the types of requests that a connection can support. Request capabilities are retrieve-only. |
CS_CAP_RESPONSE |
Response capabilities. These capabilities describe the types of responses that a server can send to a connection. An application can set response capabilities before a connection is open and can retrieve response capabilities at any time. |
The capability of interest. The following two tables list the symbolic values that are legal for capability:
In addition to the values listed in the tables, capability can
have the special value CS_ALL_CAPS,
to indicate that an application is setting or retrieving all response
or request capabilities simultaneously. CS_ALL_CAPS is
primarily of use in gateway applications. A typical Client-Library application
needs to set or retrieve only a small number of capabilities.
Table 3-5 summarizes the CS_CAP_REQUEST capabilities.
CS_CAP_REQUEST capability |
Meaning |
Capability relates to |
|---|---|---|
CS_CON_INBAND |
In-band (non-expedited) attentions. |
Connections |
CS_CON_LOGICAL |
Logical mapping. |
Connections |
CS_CON_OOB |
Out-of-band (expedited) attentions. |
Connections |
CS_CSR_ABS |
Fetch of specified absolute cursor row. |
Cursors |
CS_CSR_FIRST |
Fetch of first cursor row. |
Cursors |
CS_CSR_LAST |
Fetch of last cursor row. |
Cursors |
CS_CSR_MULTI |
Multi-row cursor fetch. |
Cursors |
CS_CSR_PREV |
Fetch previous cursor row. |
Cursors |
CS_CSR_REL |
Fetch specified relative cursor row. |
Cursors |
CS_CUR_IMPLICIT |
TDS optimized read-only cursor. |
Cursors |
CS_DATA_BIN |
Binary datatype. |
Datatypes |
CS_DATA_VBIN |
Variable-length binary type. |
Datatypes |
CS_DATA_LBIN |
Long binary datatype. |
Datatypes |
CS_DATA_BIT |
Bit datatype. |
Datatypes |
CS_DATA_BITN |
Nullable bit values. |
Datatypes |
CS_DATA_BOUNDARY |
Boundary datatype. |
Datatype |
CS_DATA_CHAR |
Character datatype. |
Datatypes |
CS_DATA_VCHAR |
Variable-length character datatype. |
Datatypes |
CS_DATA_LCHAR |
Long character datatype. |
Datatypes |
CS_DATA_DATE |
Date datatype. |
Datatypes |
CS_DATA_DATE4 |
Short datetime datatype. |
Datatypes |
CS_DATA_DATE8 |
Datetime datatype. |
Datatypes |
CS_DATA_DATETIMEN |
NULL datetime values. |
Datatypes |
CS_DATA_DEC |
Decimal datatype. |
Datatypes |
CS_DATA_FLT4 |
4-byte float datatype. |
Datatypes |
CS_DATA_FLT8 |
8-byte float datatype. |
Datatypes |
CS_DATA_FLTN |
Nullable float values. |
Datatypes |
CS_DATA_IMAGE |
Image datatype. |
Datatypes |
CS_DATA_INT1 |
Tiny integer datatype. |
Datatypes |
CS_DATA_INT2 |
Small integer datatype. |
Datatypes |
CS_DATA_INT4 |
Integer datatype. |
Datatypes |
CS_DATA_INTN |
NULL integers. |
Datatypes |
CS_DATA_INT8 |
8-integer datatype |
Datatypes |
CS_DATA_LBIN |
Long binary datatype |
Datatypes |
CS_DATA_LCHAR |
Long character datatype |
Datatypes |
CS_DATA_UINT2 |
Unsigned 2-byte integer datatype |
Datatypes |
CS_DATA_UINT4 |
Unsigned 4-byte integer datatype |
Datatypes |
CS_DATA_UINT8 |
Unsigned 8-byte integer datatype |
Datatypes |
CS_DATA_UINTN |
Unsigned datatype |
Datatypes |
CS_DATA_UCHAR |
unsigned character. |
Datatypes |
CS_DATA_UNITEXT |
unsigned character. |
Datatypes |
CS_DATA_MNY4 |
Short money datatype. |
Datatypes |
CS_DATA_MNY8 |
Money datatype. |
Datatypes |
CS_DATA_MONEYN |
NULL money values. |
Datatypes |
CS_DATA_NUM |
Numeric datatype. |
Datatypes |
CS_DATA_SENSITIVITY |
Secure Server sensitivity datatypes. |
Datatypes |
CS_DATA_TEXT |
Text datatype. |
Datatypes |
CS_DATA_TIME |
Time datatype. |
Datatypes |
CS_DATA_XML |
Variable-width character datatype. |
Datatypes |
CS_DOL_BULK |
Token for bulk copy on DOL table. |
Bulk copy |
CS_OBJECT_CHAR |
Specifies whether the server can send/recieve streaming character data. |
Java objects. |
CS_OBJECT_BINARY |
Specifies whether the server can send/receive streaming binary data. |
Streaming data. |
CS_OBJECT_JAVA1 |
Specifies whether Java object serializations can be sent/received by the server. |
Streaming data. |
CS_OPTION_GET |
Whether the client can get current option values from the server. |
Options |
CS_PROTO_BULK |
Tokenized bulk copy. |
Bulk copy |
CS_PROTO_DYNAMIC |
Descriptions for prepared statements come back at prepare time. |
Dynamic SQL |
CS_PROTO_DYNPROC |
Client-Library prepends “create proc” to a Dynamic SQL prepare statement. |
Dynamic SQL |
CS_REQ_BCP |
Bulk copy requests. |
Commands |
CS_REQ_CURSOR |
Cursor requests. |
Commands |
CS_REQ_DBRPC2 |
Large RPC name requests. |
Commands |
CS_REQ_DYN |
Dynamic SQL requests. |
Commands |
CS_REQ_LANG |
Language requests. |
Commands |
CS_REQ_MSG |
Message commands. |
Commands |
CS_REQ_MSTMT |
Multiple server commands per Client-Library language command. |
Commands |
CS_REQ_NOTIF |
Registered procedure notifications. |
Commands |
CS_REQ_PARAM |
Use PARAM/PARAMFMT TDS streams for requests. |
Commands |
CS_REQ_RESERVED1 |
Reserved for future use. |
Commands |
CS_REQ_RESERVED2 |
Reserved for future use. |
Commands |
CS_REQ_URGNOTIF |
Send notifications with the “urgent” bit set in the TDS packet header. |
Registered procedures |
CS_REQ_RPC |
Remote procedure requests. |
Commands |
CS_WIDETABLES |
Wide table support. |
Connection |
Table 3-6 summarizes the CS_CAP_RESPONSE capabilities.
CS_CAP_RESPONSE capability |
Meaning |
Capability relates to |
|---|---|---|
CS_CON_NOINBAND |
No in-band (non-expedited) attentions. |
Connections |
CS_CON_NOOOB |
No out-of-band (expedited) attentions. |
Connections |
CS_DATA_NOBIN |
No binary datatype. |
Datatypes |
CS_DATA_NOBOUNDARY |
No security boundary datatype. |
Datatypes |
CS_DATA_NOVBIN |
No variable-length binary type. |
Datatypes |
CS_DATA_NOLBIN |
No long binary datatype. |
Datatypes |
CS_DATA_NOBIT |
No bit datatype. |
Datatypes |
CS_DATA_NOCHAR |
No character datatype. |
Datatypes |
CS_DATA_NOVCHAR |
No variable-length character datatype. |
Datatypes |
CS_DATA_NOLCHAR |
No long character datatype. |
Datatypes |
CS_DATA_NODATE |
No date datatype. |
Datatypes |
CS_DATA_NODATE4 |
No short datetime datatype. |
Datatypes |
CS_DATA_NODATE8 |
No datetime datatype. |
Datatypes |
CS_DATA_NODATETIMEN |
No NULL datetime values. |
Datatypes |
CS_DATA_NODEC |
No decimal datatype. |
Datatypes |
CS_DATA_NOFLT4 |
No 4-byte float datatype. |
Datatypes |
CS_DATA_NOFLT8 |
No 8-byte float datatype. |
Datatypes |
CS_DATA_NOIMAGE |
No image datatype. |
Datatypes |
CS_DATA_NOINT1 |
No tiny integer datatype. |
Datatypes |
CS_DATA_NOINT2 |
No small integer datatype. |
Datatypes |
CS_DATA_NOINT4 |
No integer datatype. |
Datatypes |
CS_DATA_NOINT8 |
No 8-byte integer datatype. |
Datatypes |
CS_DATA_NOINTN |
No NULL integers. |
Datatypes |
CS_DATA_NOLBIN |
No long binary |
Datatypes |
CS_DATA_NOLCHAR |
No long character |
Datatypes |
CS_DATA_NOMNY4 |
No short money datatype. |
Datatypes |
CS_DATA_NOMNY8 |
No money datatype. |
Datatypes |
CS_DATA_NOMONEYN |
No NULL money values. |
Datatypes |
CS_DATA_NONUM |
No numeric datatype. |
Datatypes |
CS_DATA_NOSENSITIVITY |
No Secure Server sensitivity datatypes. |
Datatypes |
CS_DATA_NOTEXT |
No text datatype. |
Datatypes |
CS_DATA_NOTIME |
No time datatype. |
Datatypes |
CS_DATA_NOUCHAR |
No unsigned character. |
Datatypes |
CS_DATA_NOUINT2 |
No unsigned 2-byte integer datatype. |
Datatypes |
CS_DATA_NOUINT4 |
No unsigned 4-byte integer datatype. |
Datatypes |
CS_DATA_NOUINT8 |
No unsigned 8-byte integer datatype. |
Datatypes |
CS_DATA_NOUINTN |
No unsigned integer datatype. |
Datatypes |
CS_DATA_NOUNITEXT |
No unsigned short datatype. |
Datatypes |
CS_DATA_NOXML |
No variable-width character datatype. |
Datatypes |
CS_DATA_NOZEROLEN |
No zero length datatype. |
Datatypes |
CS_NOWIDETABLES |
No wide tables. |
Connection |
CS_RES_NOEED |
No extended error results. |
Results |
CS_RES_NOMSG |
No message results. |
Results |
CS_RES_NOPARAM |
Do not use PARAM/PARAMFMT TDS streams for RPC results. |
Results |
CS_RES_NOSTRIPBLANKS |
The server should not strip blanks when returning data from nullable fixed-length character columns. |
Results |
CS_RES_NOTDSDEBUG |
No TDS debug token in response to certain dbcc commands. |
Results |
CS_RES_RESERVED |
Reserved for future use |
Future |
If a capability is being set, value points to a CS_BOOL variable that has the value CS_TRUE or CS_FALSE.
If a capability is being retrieved, value points to a CS_BOOL-sized variable, which ct_capability sets to CS_TRUE or CS_FALSE.
CS_TRUE indicates that a capability is enabled. For example, if the CS_RES_NOEED capability is set to CS_TRUE, no extended error data will be returned on the connection.
If capability is CS_ALL_CAPS,
the value must point to a CS_CAP_TYPE structure.
ct_capability returns the following values:
Return value |
Meaning |
|---|---|
CS_SUCCEED |
The routine completed successfully. |
CS_FAIL |
The routine failed. |
CS_BUSY |
An asynchronous operation is already pending for this connection. For more information, see “Asynchronous programming”. |
Capabilities describe client/server features that a connection supports.
There are two types of capabilities: CS_CAP_RESPONSE capabilities, also called response capabilities, and CS_CAP_REQUEST capabilities, also called request capabilities.
An application uses request capabilities to determine what kinds of requests a server connection supports. For example, an application can retrieve the CS_REQ_CURSOR capability to find out whether a connection supports cursor requests.
An application uses response capabilities to prevent the server from sending a type of response that the application cannot process. For example, an application can prevent a server from sending NULL money values by setting the CS_DATA_NOMONEYN response capability to CS_TRUE.
Before a connection is open, an application can:
Retrieve request or response capabilities, to determine what request and response features are normally supported at the application’s current TDS (Tabular Data Stream) version level. An application’s TDS level defaults to a value based on the CS_VERSION level that the application requested in its call to ct_init.
Set response capabilities, to indicate that a connection does not wish to receive particular types of server responses. An application cannot set request capabilities, which are retrieve-only.
After a connection is open, an application can:
Retrieve request capabilities to find out what types of requests the connection supports.
Retrieve response capabilities to find out whether the server has agreed to withhold the previously indicated response types from the connection.
Capabilities are determined by a connection’s TDS version level. Not all TDS versions support the same capabilities. For example, 4.0 TDS does not support registered procedure notifications or cursor requests. However, 4.0 TDS does support bulk copy requests, remote procedure call requests, row results, and compute row results. A connection’s TDS version level is negotiated during the connection process.
If an application sets the CS_TDS_VERSION property, Client-Library overwrites existing capability values with default capability values corresponding to the new TDS version. For this reason, an application should set CS_TDS_VERSION before setting any capabilities for a connection.
Because CS_TDS_VERSION is a negotiated login property, the server can change its value at connection time. If this occurs, Client-Library overwrites existing capability values with default capability values corresponding to the new TDS version.
Because capability values can change at connection time, an application must call ct_capability after a connection is open to determine what capability values are in effect for the connection.
When a connection is closed, Client-Library resets its capability values to values corresponding to the application’s default TDS version.
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 pointer to 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.
ct_connect optionally reads a section from the Open Client and Open Server runtime configuration file to set server capabilities for a connection.
For a description of this feature, see “Using the runtime configuration file”.
“Capabilities”, ct_con_props, ct_connect, ct_options, “Properties”
