DBPROP_SERVERCURSOR | Microsoft OLE DB 2.0 Programmers Reference and Data Access SDK (Microsoft Professional Editions)

OLE DB Programmer's Reference

Property group: Rowset

Property set: DBPROPSET_ROWSET

Column? N

Type: VT_BOOL

Typical R/W: R/W

Description: Server Cursor

DBPROP_SERVERCURSOR works in conjunction with other cursor properties, including DBPROP_CLIENTCURSOR, to determine where a cursor, if required, is materialized.

If the value of this property is set to VARIANT_TRUE, the provider attempts to support any requested cursor functionality by materializing a cursor on the server. If DBPROPOPTIONS_REQUIRED is specified and materializing a cursor on the server cannot support any required cursor functionality, the provider returns an error and does not open the rowset. If DBPROPOPTIONS_OPTIONAL is specified, the provider attempts to support the requested cursor functionality at the server but may materialize a cursor on the client, if necessary, to support required properties. The provider never materializes a cursor on the client to support optional properties if DBPROP_SERVERCURSOR is set to VARIANT_TRUE.
If the value of this property is set to VARIANT_FALSE, the provider attempts to support any requested cursor functionality by materializing a cursor on the client. If DBPROPOPTIONS_REQUIRED is specified and materializing a cursor on the client cannot support any required cursor functionality, the provider returns an error and does not open the rowset. If DBPROPOPTIONS_OPTIONAL is specified, the provider attempts to support the requested functionality by materializing a cursor on the client but may materialize a cursor on the server, if necessary, to support required properties. The provider never materializes a cursor on the server to support optional properties if DBPROP_SERVERCURSOR is set to VARIANT_FALSE.

If DBPROPOPTIONS_REQUIRED is specified and this property is set to VARIANT_TRUE for a provider that does not support server-side cursors, or to VARIANT_FALSE for a provider that does not support client-side cursors, the provider returns an error. Otherwise, this property is ignored if no additional cursor properties are specified.

Local providers, for whom the data is always located on the same machine as the rowset consumer, may choose either of the following options:

Ignore this property and return DBPROPSTATUS_OK, since the server cursor and client cursor are the same thing.
Not support this property and return DBPROPSTATUS_NOTSUPPORTED.

Client/server providers, for whom the data resides on a different machine than the consumer, typically do not support client cursors. These providers generally return an error if DBPROP_SERVERCURSOR is set to VARIANT_FALSE with DBPROPOPTIONS_REQUIRED and if any other cursor properties are specified as required, or if any required properties are not supported by a cursor implemented on the server.

The following table documents the behavior for client/server providers when DBPROP_SERVERCURSOR is used in combination with any properties that request cursor functionality.

Cursor properties	_SERVERCURSOR	Cursor location (Success)	Cursor location (Failure)
true/required	true/required	Server	Error
true/required	true/optional	Server	Client or Error
true/required	false/required	Client	Error
true/required	false/optional	Client	Server or Error
true/optional	true/required	Server	Not satisfied
true/optional	true/optional	Server	Not satisfied
true/optional	false/required	Client	Not satisfied
true/optional	false/optional	Client	Not satisfied

When service components are invoked, they handle the invocation of the client-side cursor as follows:

If the consumer specifies a value of VARIANT_TRUE for DBPROP_SERVERCURSOR with DBPROPOPTIONS_REQUIRED, the service components pass the cursor properties through to the provider unchanged. If any required properties cannot be satisfied, the provider returns an error to the consumer.
If the consumer specifies a value of VARIANT_TRUE for DBPROP_SERVERCURSOR with DBPROPOPTIONS_OPTIONAL specified, the service components pass all cursor properties as DBPROPOPTIONS_OPTIONAL. If any required cursor properties could not be supported, the service components materialize a cursor on the client, populated by the provider's cursor; otherwise, they return the provider's rowset directly to the consumer.
If the consumer specifies a value of VARIANT_FALSE for DBPROP_SERVERCURSOR with DBPROPOPTIONS_REQUIRED specified, the service components determine whether or not the provider supports materializing a client cursor (by attempting to set the property on a command or by passing the specified properties unchanged to IOpenRowset::OpenRowset). If the provider cannot support the client cursor, the service components clear all cursor properties and request a forward-only rowset from the provider, which is then used to populate a client-side cursor.
If the consumer specifies a value of VARIANT_FALSE for DBPROP_SERVERCURSORS with DBPROPOPTIONS_OPTIONAL specified, the service components set the DBPROP_SERVERCURSORS property to DBPROPOPTIONS_REQUIRED and pass all cursor properties as DBPROPOPTIONS_OPTIONAL. If any required cursor properties could not be supported, the service components materialize a cursor on the client, populated by the provider's cursor.
If the consumer specifies a value of VARIANT_TRUE for DBPROP_CLIENTCURSOR, with DBPROPOPTIONS_REQUIRED specified, and uses ICommand::Execute to populate the rowset, the service components ignore any setting for DBPROP_SERVERCURSOR. The service components request a forward-only rowset from the provider, which is then used to populate a client-side cursor.