Curseurs de serveur pour API
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 OLE DB de MicrosoftSQL Server Native Client et le pilote ODBC de SQL Server Native Client implémentent ces opérations via l'utilisation de curseurs côté serveur d'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 :
ouvrir une connexion ;
paramétrer les attributs ou les propriétés définissant les caractéristiques du curseur que l'API mappe automatiquement sur chaque jeu de résultats ;
exécuter une ou plusieurs instructions Transact-SQL ;
utiliser les fonctions ou les méthodes de l'API pour extraire des lignes des ensembles de résultats.
Lorsque les valeurs par défaut sont affectées aux attributs ou aux propriétés du curseur de l'API, le fournisseur OLE DB de SQL Server Native Client et le pilote ODBC de SQL Server Native Client utilisent les jeux 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 jeu 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 jeu 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 traitementTransact-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 valeurs par défaut ne sont pas affectées aux attributs ou aux propriétés du curseur de l'API, le fournisseur OLE DB de SQL Server Native Client et le pilote ODBC de SQL Server Native Client utilisent des curseurs côté serveur d'API plutôt que des jeux 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 traitementss 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 de SQL Server Native Client et le pilote ODBC de SQL Server Native Client utilisent ces procédures stockées système spéciales 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 traitements 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 traitements 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 exclusivement réservées à l'usage interne du fournisseur OLE DB de SQL Server Native Client et du pilote ODBC de SQL Server 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, le jeu 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 le jeu 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 le jeu 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 le jeu 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 le jeu 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 le jeu 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 le jeu 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 le jeu 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 du jeu 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, 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_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 |