Cursores de servidor de la API

Las API de OLE DB, ODBC y ADO admiten la asignación de cursores en los conjuntos de resultados de las instrucciones SQL ejecutadas. El proveedor OLE DB de Microsoft SQL Native Client y el controlador ODBC de SQL Native Client implementan estas operaciones mediante el uso de cursores de servidor de la API. Los servidores de cursor de la API son cursores implementados en el servidor y administrados por las funciones de cursor de la API. A medida que la aplicación llama a las funciones de cursor de la API, la operación del cursor se transmite al servidor mediante el proveedor OLE DB o el controlador ODBC.

Cuando utilice un cursor de servidor de la API en OLE DB, ODBC y ADO, utilice las funciones o métodos de la API para:

1. Abrir una conexión.
2. Establecer los atributos o propiedades que definen las características del cursor que la API asigna automáticamente en cada conjunto de resultados.
3. Ejecutar una o varias instrucciones Transact-SQL.
4. Utilizar funciones o métodos de la API para recopilar las filas de los conjuntos de resultados.

Cuando los atributos o propiedades del cursor de la API utilizan su configuración predeterminada, el proveedor OLE DB de SQL Native Client y el controlador ODBC de SQL Native Client utilizan conjuntos de resultados predeterminados. Aunque la API solicite técnicamente un cursor, las características del cursor predeterminado coinciden con el comportamiento de un conjunto de resultados predeterminado. Por lo tanto, el proveedor OLE DB y el controlador ODBC implementan las opciones del cursor predeterminado mediante un conjunto de resultados predeterminado, puesto que ésta es la forma más eficaz de recuperar filas del servidor. Cuando se utilizan conjuntos de resultados predeterminados, una aplicación puede ejecutar cualquier instrucción o lote de Transact-SQL, pero sólo puede tener una instrucción pendiente en una conexión. Esto significa que la aplicación debe procesar o cancelar todos los conjuntos de resultados que devuelve una instrucción antes de poder ejecutar otra instrucción en la conexión.

Cuando los atributos o propiedades de cursores de la API utilizan un valor que no es el predeterminado, el proveedor OLE DB de SQL Native Client y el controlador ODBC de SQL Native Client utilizan cursores de servidor de la API en lugar de conjuntos de resultados predeterminados. Cada llamada a una función de la API que recopile filas genera un ciclo de ida y vuelta al servidor para recopilar las filas del cursor de servidor de la API.

Restricciones de los cursores de servidor de la API

Una aplicación no puede ejecutar las instrucciones siguientes cuando utiliza cursores de servidor de la API:

• Las instrucciones Transact-SQL que SQL Server no admite en los cursores de servidor.
• Lotes o procedimientos almacenados que devuelven varios conjuntos de resultados.
• Instrucciones SELECT que contienen cláusulas COMPUTE, COMPUTE BY, FOR BROWSE o INTO.
• Una instrucción EXECUTE que haga referencia a un procedimiento almacenado remoto.

Implementación de cursores de servidor de la API

El proveedor de OLE DB de SQL Native Client y el controlador ODBC de SQL Native Client utilizan estos procedimientos almacenados del sistema especiales para indicar al servidor las operaciones de cursor:

• sp_cursoropen define la instrucción SQL que se desea asociar con el cursor y las opciones de éste; a continuación, llena el cursor.
• sp_cursorfetch recopila una fila o bloque de filas del cursor.
• sp_cursorclose cierra y cancela la asignación del cursor.
• sp_cursoroption se utiliza para establecer diversas opciones de cursor.
• sp_cursor se utiliza para solicitar actualizaciones posicionadas.
• sp_cursorprepare compila la instrucción o lote de Transact-SQL asociado con un cursor en un plan de ejecución pero no crea el cursor.
• sp_cursorexecute crea y llena un cursor a partir del plan de ejecución creado por sp_cursorprepare.
• sp_cursorunprepare descarta el plan de ejecución de sp_cursorprepare.
• sp_cursorprepexec compila un plan para la instrucción o lote de Transact-SQL enviados asociados con un cursor, crea el cursor y lo llena. sp_cursorprepexec combina el comportamiento de sp_cursorprepare y sp_cursorexecute.

Estos procedimientos almacenados del sistema se mostrarán en las trazas del Analizador de SQL Server de las aplicaciones ADO, OLE DB y ODBC que utilicen cursores de servidor de la API. Se han diseñado sólo para uso interno del proveedor OLE DB de SQL Native Client y el controlador ODBC de SQL Native Client. La funcionalidad completa de estos procedimientos está disponible para las aplicaciones con sólo utilizar la funcionalidad de cursor de las API de base de datos. No se admite la especificación directa de procedimientos en una aplicación.

Cuando SQL Server ejecuta una instrucción en una conexión, es preciso esperar hasta que se hayan procesado o cancelado todos los resultados de esta instrucción para poder ejecutar otras. Esta regla se mantiene cuando se utilizan cursores de servidor de la API, pero para la aplicación es como si SQL Server hubiese comenzado a admitir varias instrucciones activas en una conexión. Esto se debe a que el conjunto de resultados completo se almacena en el cursor de servidor y las únicas instrucciones que se transmiten a SQL Server son las ejecuciones de los procedimientos almacenados sp_cursor del sistema. SQL Server ejecuta el procedimiento almacenado y, en cuanto el cliente recupera el conjunto de resultados, ya puede ejecutar cualquier otra instrucción. El proveedor OLE DB y el controlador ODBC siempre recuperan todos los resultados de un procedimiento almacenado sp_cursor antes de devolver el control a la aplicación. Esto permite a las aplicaciones intercalar las recopilaciones realizadas en varios cursores de servidor activos.

Esta tabla muestra la forma en que una aplicación puede procesar dos cursores al mismo tiempo en una conexión con sólo utilizar dos identificadores de instrucciones.

Debido a que no quedan resultados pendientes en la conexión después de llamar a un procedimiento almacenado sp_cursor, se pueden ejecutar varias instrucciones Transact-SQL simultáneamente en una única conexión, siempre y cuando todas se ejecuten con cursores de servidor de la API.

Especificar cursores de servidor de la API

A continuación se muestra un resumen de cómo se utilizan los cursores de servidor de la API en las API:

• OLE DB
  • Abra un objeto de sesión, abra un objeto de comando y especifique el texto del comando.
  • Establezca propiedades del conjunto de filas como DBPROP_OTHERINSERT, DBPROP_OTHERUPDATEDELETE, DBPROP_OWNINSERT o DBPROP_OWNUDPATEDELETE para controlar el comportamiento del cursor.
  • Ejecute el objeto de comando.
  • Recupere las filas del conjunto de resultados utilizando métodos como IRowset::GetNextRows, IRowsetLocate::GetRowsAt, IRowsetLocate::GetRowsAtBookmark e IRowsetScroll::GetRowsAtRatio.
• ODBC
  • Abra una conexión y llame a SQLAllocHandle para asignar identificadores de instrucciones.
  • Llame a SQLSetStmtAttr para establecer los atributos SQL_ATTR_CURSOR_TYPE, SQL_ATTR_CONCURRENCY y SQL_ATTR_ROW_ARRAY_SIZE. También puede especificar comportamientos de cursores si establece los atributos SQL_ATTR_CURSOR_SCROLLABLE y SQL_ATTR_CURSOR_SENSITIVITY.
  • Ejecute una instrucción Transact-SQL con SQLExecDirect o SQLPrepare y SQLExecute.
  • Recopile filas o bloques de filas con SQLFetch o SQLFetchScroll.
• ADO
  • Defina un objeto Connection y un objeto Recordset y, a continuación, ejecute el método Open del objeto Connection.
  • Ejecute el método Open del objeto Recordset y especifique los parámetros CursorType y LockType o bien uno de los dos.
  • Recopile las filas con los métodos Move, MoveFirst, MoveLast, MoveNext y MovePrevious del objeto Recordset.

Cursores de servidor de la API y opciones SET

En SQL Server 2005, si se emite una instrucción de recopilación y se produce un cambio en alguna de las siguientes opciones que afectan al plan o en las opciones necesarias para las vistas indizadas o las columnas calculadas, el cursor utiliza una instantánea de los valores de opción vigentes en el momento en que se abre el cursor. Estos valores se utilizan en todas las operaciones de recopilación posteriores y se pasan por alto los cambios en el contexto actual.

Vea también

Otros recursos

Rowsets and SQL Server Cursors
Using Cursors

Ayuda e información

Obtener ayuda sobre SQL Server 2005