Curseurs de serveur pour API

  • Article

Les API OLE DB, ODBC et ADO prennent en charge le mappage de curseurs sur les ensembles de résultats des instructions SQL exécutées. Le fournisseur Microsoft OLE DB SQL Native Client et le pilote ODBC SQL Native Client implémentent ces opérations grâce à l'utilisation de curseurs de serveur pour API. Les curseurs de serveur pour API sont implémentés sur le serveur et gérés par les fonctions de curseur pour API. Lorsque l'application appelle ces dernières, l'opération du curseur est transmise au serveur par le fournisseur OLE DB ou le pilote ODBC.

En cas d'utilisation d'un curseur de serveur pour API dans OLE DB, ODBC et ADO, utilisez les fonctions ou les méthodes de l'API pour :

  1. ouvrir une connexion ;
  2. paramétrer les attributs ou les propriétés définissant les caractéristiques du curseur que l'API mappe automatiquement sur chaque ensemble de résultats ;
  3. exécuter une ou plusieurs instructions Transact-SQL ;
  4. utiliser les fonctions ou les méthodes de l'API pour extraire des lignes des ensembles de résultats.

Lorsque les attributs ou les propriétés du curseur de l'API sont affectés de leurs valeurs par défaut, le fournisseur OLE DB SQL Native Client et le pilote ODBC SQL Native Client utilisent les ensembles de résultats par défaut. Bien que l'API ait techniquement besoin d'un curseur, les caractéristiques du curseur par défaut correspondent au comportement d'un ensemble de résultats par défaut. Par conséquent, le fournisseur OLE DB et le pilote ODBC implémentent les options de curseur par défaut à l'aide d'un ensemble de résultats par défaut, car cette méthode est la plus efficace pour extraire des lignes du serveur. En cas d'utilisation d'ensembles de résultats par défaut, une application peut exécuter une instruction ou un lot d'instructions Transact-SQL mais ne peut avoir qu'une instruction en attente sur une connexion. Cela signifie que l'application doit traiter ou annuler tous les ensembles de résultats retournés par une instruction avant de pouvoir exécuter une autre instruction sur la connexion.

Lorsque les attributs ou les propriétés du curseur de l'API ne sont pas affectés de leurs valeurs par défaut, le fournisseur OLE DB SQL Native Client et le pilote ODBC SQL Native Client utilisent des curseurs de serveur pour API à la place d'ensembles de résultats par défaut. Chaque appel d'une fonction API permettant l'extraction de lignes génère un aller-retour vers le serveur afin d'extraire les lignes du curseur de serveur pour API.

Restrictions relatives aux curseurs de serveur pour API

En cas d'utilisation de curseurs de serveur pour API, une application ne peut pas exécuter les instructions suivantes :

  • Les instructions Transact-SQL que SQL Server ne prend pas en charge dans les curseurs de serveur.
  • Les lots d'instructions ou les procédures stockées qui retournent plusieurs ensembles de résultats.
  • Les instructions SELECT contenant les clauses COMPUTE, COMPUTE BY, FOR BROWSE ou INTO.
  • Une instruction EXECUTE faisant référence à une procédure stockée distante.

Implémentation des curseurs de serveur pour API

Le fournisseur OLE DB SQL Native Client et le pilote ODBC SQL Native Client utilisent ces procédures stockées spéciales du système pour signaler les opérations de curseur au serveur :

  • sp_cursoropen définit l'instruction SQL devant être associée au curseur et à ses options, puis remplit le curseur.
  • sp_cursorfetch extrait une ligne ou un bloc de lignes à partir du curseur.
  • sp_cursorclose ferme et désalloue le curseur.
  • sp_cursoroption permet de définir plusieurs options de curseur.
  • sp_cursor permet de demander des mises à jour positionnées.
  • sp_cursorprepare compile l'instruction ou le lot d'instructions Transact-SQL associé à un curseur dans un plan d'exécution, mais ne crée pas le curseur.
  • sp_cursorexecute crée et remplit un curseur à partir du plan d'exécution créé par sp_cursorprepare.
  • sp_cursorunprepare rejette le plan d'exécution à partir de sp_cursorprepare.
  • sp_cursorprepexec compile un plan pour l'instruction ou le lot d'instructions Transact-SQL soumis associé à un curseur, crée le curseur puis le remplit. sp_cursorprepexec combine le comportement de sp_cursorprepare et sp_cursorexecute.

Ces procédures stockées du système permettent d'obtenir dans le générateur de profils SQL Server Profiler des traces d'applications ADO, OLE DB et ODBC utilisant des curseurs de serveur API. Elles sont uniquement réservées à l'usage interne du fournisseur OLE DB SQL Native Client et du pilote ODBC SQL Native Client. Les applications peuvent accéder à l'intégralité des fonctionnalités de ces procédures par l'intermédiaire des fonctions de curseur de l'API de la bases de données. Vous ne pouvez pas spécifier les procédures directement dans une application.

Lorsque SQL Server exécute une instruction sur une connexion, aucune autre instruction ne peut être exécutée sur la connexion tant que tous les résultats de la première instruction n'ont pas été traités ou annulés. Cette règle reste en vigueur en cas d'utilisation de curseurs de serveur API mais, au niveau de l'application, c’est comme si SQL Server avait commencé à prendre en charge plusieurs instructions actives sur une connexion. En effet, l'ensemble de résultats complet est stocké dans le curseur de serveur et les seules instructions transmises à SQL Server sont les exécutions des procédures stockées sp_cursor du système. SQL Server exécute la procédure stockée et, dès que le client extrait l'ensemble de résultats, il peut exécuter une autre instruction. Le fournisseur OLE DB et le pilote ODBC procèdent toujours à l'extraction des résultats à partir d'une procédure stockée sp_cursor avant de redonner le contrôle à l'application. Ceci permet aux applications d'entrelacer les lignes extraites de plusieurs curseurs de serveur actifs.

Ce tableau explique comment une application peut traiter simultanément deux curseurs sur une connexion à l'aide de deux pointeurs d'instruction.

Descripteur d'instruction 1 Descripteur d'instruction 2

Définir les attributs de curseur pour qu'un curseur de serveur API soit utilisé.

 

SQLExecDirect une instruction SQL. Le pilote ODBC appelle sp_cursoropen et récupère l'ensemble de résultats retourné par la procédure.

 

 

Définir les attributs de curseur pour qu'un curseur de serveur API soit utilisé.

 

SQLExecDirect une instruction SQL. Le pilote ODBC appelle sp_cursoropen et récupère l'ensemble de résultats retourné par la procédure.

SQLFetchScroll pour extraire le premier bloc de lignes. Le pilote appelle sp_cursorfetch puis récupère l'ensemble de résultats retourné par la procédure.

 

 

SQLFetchScroll pour extraire le premier bloc de lignes. Le pilote appelle sp_cursorfetch puis récupère l'ensemble de résultats retourné par la procédure.

SQLFetchScroll pour extraire un autre bloc de lignes. Le pilote appelle sp_cursorfetch puis récupère l'ensemble de résultats retourné par la procédure.

 

 

SQLFetchScroll pour extraire un autre bloc de lignes. Le pilote appelle sp_cursorfetch puis récupère l'ensemble de résultats retourné par la procédure.

Appelez SQLFreeStmt ou SQLCloseCursor . Le pilote appelle sp_cursorclose.

 

 

Appelez SQLFreeStmt ou SQLCloseCursor . Le pilote appelle sp_cursorclose.

Étant donné qu'aucun résultat ne reste en attente sur la connexion suite à l'appel d'une procédure stockée sp_cursor, vous pouvez exécuter simultanément plusieurs instructions Transact-SQL sur une seule connexion, à condition que celles-ci soient toutes exécutées à l'aide de curseurs de serveur API.

Spécification des curseurs de serveur API

Les procédures ci-dessous indiquent brièvement comment utiliser les curseurs de serveur pour API dans les API :

  • OLE DB
    • Ouvrez un objet de session, ouvrez un objet de commande et spécifiez le texte de la commande.
    • Pour gérer le comportement des curseurs, définissez les propriétés de l'ensemble de lignes, telles que DBPROP_OTHERINSERT, DBPROP_OTHERUPDATEDELETE, DBPROP_OWNINSERT, DBPROP_OWNUDPATEDELETE.
    • Exécutez l'objet de commande.
    • Extrayez les lignes de l'ensemble de résultats à l'aide de méthodes telles que IRowset::GetNextRows, IRowsetLocate::GetRowsAt, IRowsetLocate::GetRowsAtBookmark et IRowsetScroll::GetRowsAtRatio.
  • ODBC
    • Ouvrez une connexion et appelez SQLAllocHandle pour allouer des pointeurs d'instruction.
    • Appelez SQLSetStmtAttr pour définir les attributs SQL_ATTR_CURSOR_TYPE, SQL_ATTR_CONCURRENCY et SQL_ATTR_ROW_ARRAY_SIZE. Vous pouvez également spécifier le comportement des curseurs en définissant les attributs SQL_ATTR_CURSOR_SCROLLABLE et SQL_ATTR_CURSOR_SENSITIVITY.
    • Exécutez une instruction Transact-SQL à l'aide de SQLExecDirect ou SQLPrepare et de SQLExecute.
    • Extrayez les lignes ou blocs de lignes à l'aide de SQLFetch ou SQLFetchScroll.
  • ADO
    • Définissez un objet Connection et un objet Recordset, puis exécutez la méthode Open sur l'objet Connection.
    • Exécutez la méthode Open sur l'objet Recordset en spécifiant un paramètre CursorType et/ou LockType.
    • Extrayez des lignes à l'aide des méthodes de jeux d'enregistrements Move, MoveFirst, MoveLast, MoveNext et MovePrevious.

Curseurs de serveur pour API et options SET

Dans SQL Server 2005, si une instruction d'extraction est émise puis qu'une modification est apportée à l'une des options affectant le plan suivantes ou à l'une des options requises pour les vues indexées ou les colonnes calculées, le curseur utilise une capture instantanée des valeurs d'option en vigueur à l'ouverture du curseur. Ces valeurs sont utilisées pour toutes les opérations d'extraction ultérieures et les modifications apportées au contexte actuel sont ignorées.

Options affectant le plan

ARITHABORT

NUMERIC_ROUNDABORT

FORCEPLAN

QUOTED_IDENTIFIER

ANSI_NULL_DFLT_ON

ANSI_NULL_DFLT_OFF

ANSI_WARNINGS

ANSI_PADDING

ANSI_NULLS

CONCAT_NULL_YIELDS_NULL

DATEFIRST

DATEFORMAT

LANGUAGE

TEXTSIZE

Vues indexées et colonnes calculées

ANSI_NULLS

ANSI_PADDING

ANSI_WARNINGS

ARITHABORT (lorsque le niveau de compatibilité est inférieur ou égal à 80) CONCAT_NULL_YIELDS_NULL

QUOTED_IDENTIFIER

NUMERIC_ROUNDABORT

Voir aussi

Autres ressources

Rowsets and SQL Server Cursors
Using Cursors

Aide et Informations

Assistance sur SQL Server 2005