ct_capability

Description

Set or retrieve a client/server capability.

Syntax

CS_RETCODE ct_capability(connection, action, type,
                 capability, value)
 
 CS_CONNECTION    *connection;
 CS_INT                      action;
 CS_INT                      type;
 CS_INT                      capability;
 CS_VOID                   *value;

Parameters

connection

A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/server connection.

action

One of the following symbolic values:

Value of action

Meaning

CS_SET

Sets a capability

CS_GET

Retrieves a capability

type

The type category of the capability. The following table lists the symbolic values for type:

Table 3-4: Values for ct_capability type parameter

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.

capability

The capability of interest. The following two tables list the symbolic values that are legal for capability:

NoteIn 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.

Table 3-5: 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_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_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_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_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.

Table 3-6: 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

ADITYA*

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_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_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_NOUNIT8

No unsigned 8-byte integer datatype

Datatypes

CS_DATA_NOUINTN

No unsigned integer 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

Don’t use PARAM/PARAMFMT TDS streams for RPC results.

Results

CS_RES_NOSTRIPBLANKS

The server shouldn’t 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

value

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.

NoteIf capability is CS_ALL_CAPS, the value must point to a CS_CAP_TYPE structure.

Returns

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”.

Usage


Setting and retrieving multiple capabilities


Configuring capabilities externally

See also

“Capabilities”, ct_con_props, ct_connect, ct_options, “Properties”