Cursores de servidor de API
As APIs de OLE DB, ODBC e ADO oferecem suporte a cursores de mapeamento dos conjuntos de resultados de instruções SQL executadas. O provedor OLE DB e o driver ODBC do Microsoft SQL Server Native Client implementam essas operações através de cursores de servidor de API. Os cursores de servidor de API são cursores implementados no servidor e gerenciados por funções de cursor de API. Enquanto o aplicativo chama as funções de cursor de API, a operação do cursor é transmitida ao servidor pelo provedor OLE DB ou pelo driver ODBC.
Ao usar um cursor de servidor de API no OLE DB, ODBC e ADO, use as funções ou métodos da API para:
Abrir uma conexão.
Definir atributos ou propriedades especificando as características do cursor que a API mapeia automaticamente para cada conjunto de resultados.
Executar uma ou mais instruções Transact-SQL.
Usar funções ou métodos da API para buscar as linhas nos conjuntos de resultados.
Quando as propriedades ou os atributos do cursor da API são definidos com as suas configurações padrão, o provedor OLE DB e o driver ODBC do SQL Server Native Client usam os conjuntos de resultados padrão. Embora a API esteja tecnicamente solicitando um cursor, as características do cursor padrão correspondem ao comportamento de um conjunto de resultados padrão. O provedor OLE DB e o driver ODBC, implementam então as opções de cursor padrão que usam um conjunto de resultados padrão porque esse é o modo mais eficiente para recuperar linhas de um servidor. Ao usar conjuntos de resultados padrão, um aplicativo pode executar qualquer lote ou instrução Transact-SQL, mas pode ter apenas uma instrução pendente em uma conexão. Isso significa que o aplicativo deve processar ou cancelar todos os conjuntos de resultados retornados por uma instrução antes de poder executar outra instrução na conexão.
Quando os atributos de cursor de API ou propriedades são definidos de modo diferente de seus padrões, o provedor OLE DB e o driver ODBC do SQL Server Native Client usam os cursores de servidor de API em vez de conjuntos de resultados padrão. Cada chamada para uma função de API que busca linhas gera uma viagem de ida e volta ao servidor para buscar as linhas do cursor de servidor de API.
Restrições do cursor de servidor de API
Um aplicativo não pode executar as seguintes instruções ao usar os cursores de servidor de API:
Instruções Transact-SQL para as quais o SQL Server não oferece suporte nos cursores de servidor.
Lotes ou procedimentos armazenados que retornam vários conjuntos de resultados.
Instruções SELECT que contêm cláusulas COMPUTE, COMPUTE BY, FOR BROWSE ou INTO.
Uma instrução EXECUTE que faz referência a um procedimento armazenado remoto.
Implementação de cursor de servidor de API
O provedor OLE DB e o driver ODBC do SQL Server Native Client usam esses procedimentos armazenados especiais do sistema para sinalizar operações de cursor para o servidor:
sp_cursoropen define a instrução SQL a ser associada ao cursor e as opções de cursor e, em seguida, popula o cursor.
sp_cursorfetch busca uma linha ou um bloco de linhas no cursor.
sp_cursorclose fecha e desaloca o cursor.
sp_cursoroption é usado para definir várias opções de cursor.
sp_cursor é usado para solicitar atualizações posicionadas.
sp_cursorprepare compila a instrução Transact-SQL ou o lote associado a um cursor em um plano de execução, mas não cria o cursor.
sp_cursorexecute cria e popula um cursor a partir do plano de execução criado pelo sp_cursorprepare.
sp_cursorunprepare descarta o plano de execução de sp_cursorprepare.
sp_cursorprepexec compila um plano para a instrução Transact-SQL enviada ou para o lote associado a um cursor, cria o cursor e o popula. sp_cursorprepexec combina o comportamento de sp_cursorprepare e sp_cursorexecute.
Esses procedimentos armazenados do sistema aparecerão em rastreamentos do SQL Server Profiler de aplicativos ODBC, ADO e OLE DB que estão usando cursores de servidor de API. Eles se destinam apenas a uso interno do provedor OLE DB e do driver de ODBC do SQL Server Native Client. A funcionalidade total desses procedimentos está disponível para os aplicativos através do uso da funcionalidade de cursor de APIs de banco de dados. Não há suporte para a especificação de procedimentos diretamente em um aplicativo.
Quando o SQL Server executa uma instrução para uma conexão, nenhuma outra instrução pode ser executada na conexão até que todos os resultados da primeira instrução tenham sido processados ou cancelados. Essa regra também é mantida ao usar cursores de servidor de API, mas para o aplicativo parece que o SQL Server iniciou oferecendo suporte a várias instruções ativas em uma conexão. A razão é que o conjunto de resultados completo é armazenado no cursor de servidor e as únicas instruções que são transmitidas ao SQL Server são as execuções dos procedimentos armazenados do sistema sp_cursor. O SQL Server executa o procedimento armazenado e assim que o cliente recupera o conjunto de resultados ele pode executar qualquer outra instrução. O provedor OLE DB e o driver ODBC sempre recuperam todos os resultados de um procedimento armazenado sp_cursor antes que eles devolvam o controle ao aplicativo. Isso permite aos aplicativos intercalarem buscas nos vários cursores de servidor ativos.
Esta tabela mostra como um aplicativo pode processar dois cursores ao mesmo tempo em uma conexão que usa dois identificadores de instrução.
Identificador de instrução 1 |
Identificador de instrução 2 |
|---|---|
Define atributos de cursor de forma um que cursor de servidor de API seja usado. |
|
SQLExecDirect - uma instrução SQL. O driver ODBC chama sp_cursoropen e recupera o conjunto de resultados retornado pelo procedimento. |
|
|
Define atributos de cursor de forma que cursor de servidor de API seja usado. |
|
SQLExecDirect - uma instrução SQL. O driver ODBC chama sp_cursoropen e recupera o conjunto de resultados retornado pelo procedimento. |
SQLFetchScroll para recuperar o primeiro bloco de linhas. O driver chama sp_cursorfetch e, em seguida, recupera o conjunto de resultados retornado pelo procedimento. |
|
|
SQLFetchScroll para recuperar o primeiro bloco de linhas. O driver chama sp_cursorfetch e, em seguida, recupera o conjunto de resultados retornado pelo procedimento. |
SQLFetchScroll para recuperar outro bloco de linhas. O driver chama sp_cursorfetch e, em seguida, recupera o conjunto de resultados retornado pelo procedimento. |
|
|
SQLFetchScroll para recuperar outro bloco de linhas. O driver chama sp_cursorfetch e, em seguida, recupera o conjunto de resultados retornado pelo procedimento. |
Chama SQLFreeStmt ou SQLCloseCursor. O driver chama sp_cursorclose. |
|
|
Chama SQLFreeStmt ou SQLCloseCursor. O driver chama sp_cursorclose. |
Como nenhum resultado fica pendente na conexão após qualquer chamada para um procedimento armazenado sp_cursor, você pode executar várias instruções Transact-SQL simultaneamente em uma única conexão, contanto que todas sejam executadas com cursores de servidor de API.
Especificando cursores de servidor de API
Este é um resumo de como os cursores de servidor de API são usados nas APIs:
OLE DB
Abra um objeto de sessão, abra um objeto de comando e especifique o texto do comando.
Defina as propriedades de conjunto de linhas, como DBPROP_OTHERINSERT, DBPROP_OTHERUPDATEDELETE, DBPROP_OWNINSERT, DBPROP_OWNUDPATEDELETE, para controlar os comportamentos de cursor.
Executa o objeto de comando.
Busque as linhas no conjunto de resultados usando métodos como IRowset::GetNextRows, IRowsetLocate::GetRowsAt, IRowsetLocate::GetRowsAtBookmark e IRowsetScroll::GetRowsAtRatio.
ODBC
Abra uma conexão e chame SQLAllocHandle para alocar identificadores de instrução.
Chame SQLSetStmtAttr para definir os atributos SQL_ATTR_CURSOR_TYPE, SQL_ATTR_CONCURRENCY e SQL_ATTR_ROW_ARRAY_SIZE. Opcionalmente, você pode especificar comportamentos de cursor definindo os atributos SQL_ATTR_CURSOR_SCROLLABLE e SQL_ATTR_CURSOR_SENSITIVITY.
Execute uma instrução Transact-SQL usando SQLExecDirect ou SQLPrepare e SQLExecute.
Busque linhas ou blocos de linhas usando SQLFetch ou SQLFetchScroll.
ADO
Defina um objeto Connection e um objeto Recordset e, em seguida, execute o método Open no objeto Connection.
Execute o método Open no objeto Recordset especificando um parâmetro CursorType e/ou LockType.
Busque linhas usando os métodos de conjuntos de registros Move, MoveFirst, MoveLast, MoveNext e MovePrevious.
Cursores de servidor de API e opções SET
No SQL Server, se uma instrução for emitida e houver uma alteração em qualquer uma das seguintes opções que afetam o plano ou nas opções necessárias às exibições indexadas ou colunas computadas, o cursor usa um instantâneo dos valores em vigor no momento em que o cursor é aberto. Esses valores são usados para todas as operações de busca subseqüentes e as alterações no contexto atual são ignoradas.
Opções que afetam o plano |
ARITHABORT NUMERIC_ROUNDABORT FORCEPLAN QUOTED_IDENTIFIER ANSI_NULL_DFLT_ON ANSI_WARNINGS ANSI_PADDING ANSI_NULLS CONCAT_NULL_YIELDS_NULL DATEFIRST DATEFORMAT LANGUAGE TEXTSIZE |
Exibições indexadas e colunas computadas |
ANSI_NULLS ANSI_PADDING ANSI_WARNINGS ARITHABORT (no nível de compatibilidade de 80 ou inferior) CONCAT_NULL_YIELDS_NULL QUOTED_IDENTIFIER NUMERIC_ROUNDABORT |